Azure / Azure/azure-sdk-for-python
[ContentUnderstanding] Expose analyze result/status retrieval by operation_id for stateless (event-driven) consumers
- Vorherrschende Sprache
- Python
- Sterne
- 5.6k
- Forks
- 3.4k
- Ø Merge
- 2 T. 2 Std.
- Gemergte PRs (30 T.)
- 213
Beschreibung
### Library name
azure-ai-contentunderstanding (1.2.0b3)
### Is your feature request related to a problem? Please describe.
In an event-driven / message-based architecture, the worker that *starts* an
analyze operation is often not the same process (or host) that later *retrieves*
the result. The submitting worker enqueues a message and moves on; a separate
consumer picks the work up later to fetch the outcome.
Today the SDK only supports awaiting the returned `AnalyzeLROPoller`
(`poller.result()`), which requires keeping the poller object alive in the
originating process. That does not fit a stateless consumer.
The documented cross-process alternative — `poller.continuation_token()` +
`ContentUnderstandingClient(...).begin_analyze(... continuation_token=...)` /
`from_continuation_token(...)` — is impractical here because the continuation
token is a multi-KB, base64-encoded JSON blob that embeds the entire initial
HTTP exchange (request line + headers, response status + headers, and the
base64-encoded response body). Persisting that per operation onto a queue or
into a database is heavy and opaque.
Meanwhile, the service already exposes a clean primitive:
`GET /analyzerResults/{operationId}` returns status + result + usage in a single
call, keyed only by the short `operationId`. The SDK even surfaces that id today
via `AnalyzeLROPoller.operation_id`. But the client method that calls this
endpoint (`_get_result`) is marked internal (`@access(Access.internal)`), so
there is no supported public way to go from an `operation_id` back to the result.
### Describe the solution you'd like
A public, non-blocking method on both the sync and async clients that takes just
the `operation_id`:
```python
status = client.get_analyze_result(operation_id) # -> ContentAnalyzerAnalyzeOperationStatus
status.status # NotStarted | Running | Succeeded | Failed | Canceled
status.result # AnalysisResult (present once Succeeded)
status.usage # UsageDetails
status.error # ODataV4Format (present on Failed)
```
The return model `ContentAnalyzerAnalyzeOperationStatus` is already public in the
API surface. A consumer would then only need to persist the short `operation_id`
(already available from `poller.operation_id`), and any worker could poll status
or fetch the completed result statelessly.
### Describe alternatives you've considered
- **Continuation token** (`poller.continuation_token()`): works, but the token is
a large opaque blob embedding the whole initial response — undesirable to
persist and pass around per operation in a messaging system.
- **Calling the internal `_get_result(operation_id)` directly**: unsupported,
underscore-prefixed, and may change or break on TypeSpec regeneration.
### Additional context
`operation_id` is the natural correlation key (a short GUID from the
`Operation-Location` header). Related precedent in this package for small
ergonomic patches to the CU Python client that were accepted: #45432 (polling
interval) and #46249 (usage property, shipped in #46278).
I'm willing to contribute this — a PR to follow.
Beitragsleitfaden
Rechercherichtung
Beginne damit, die sync- und async-Client-Einstiegspunkte von azure-ai-contentunderstanding zu finden, und lies dann die vorhandene interne _get_result-Methode sowie das öffentliche ContentAnalyzerAnalyzeOperationStatus-Modell. Prüfe, wie Clientmethoden und Tests organisiert sind, bevor du Abdeckung für beide Clients hinzufügst. Als abgeschlossen gilt die Aufgabe, wenn eine nicht blockierende operation_id-Abfrage öffentlich in synchroner und asynchroner Form verfügbar ist und die dokumentierten Status-, Ergebnis-, Nutzungs- und Fehlerfelder zurückgibt.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- python
- Bereich
- api
- Issue-Typ
- Feature
- Schwierigkeit
- 3/5
- Geschätzter Aufwand
- 1-2 Tage
- Aktivitätsstatus
- Ruhig
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 58/100