Azure / Azure/azure-sdk-for-python

[ContentUnderstanding] Expose analyze result/status retrieval by operation_id for stateless (event-driven) consumers

Aperta
#47,951 1 commento 1 reazione 0 assegnatari Vedi su GitHub
Client Cognitive - Content Understanding customer-reported needs-team-attention question Service Attention
Lingua principale
Python
Stelle
5.6k
Fork
3.4k
Merge medio
2g
PR unite (30g)
217

Descrizione

### 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.

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Inizia individuando i punti di ingresso dei client sync e async di azure-ai-contentunderstanding, quindi leggi il metodo interno _get_result esistente e il modello pubblico ContentAnalyzerAnalyzeOperationStatus. Verifica come sono organizzati i metodi dei client e i test prima di aggiungere la copertura per entrambi i client. Il lavoro è completato quando una ricerca non bloccante di operation_id è disponibile pubblicamente nelle forme sync e async e restituisce i campi documentati relativi a stato, risultato, utilizzo ed errore.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
python
Ambito
api
Tipo di issue
Funzionalità
Difficoltà
3/5
Tempo stimato
1-2 giorni
Stato di attività
Tranquilla
Chiarezza
Abbastanza chiara
Idoneità per principianti
58/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.