Azure / Azure/azure-sdk-for-python

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

Open
#47,951 1 comment 1 reaction 0 assignees View on GitHub
Client Cognitive - Content Understanding customer-reported needs-team-attention question Service Attention
Dominant language
Python
Stars
5.6k
Forks
3.4k
Avg merge
1d 21h
Merged PRs (30d)
193

Description

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

Contributor guide

Open the contributing guide

Research direction

Start by locating the azure-ai-contentunderstanding sync and async client entry points, then read the existing internal _get_result method and the public ContentAnalyzerAnalyzeOperationStatus model. Check how client methods and tests are organized before adding coverage for both clients. Done means a non-blocking operation_id lookup is publicly available in sync and async forms and returns the documented status, result, usage, and error fields.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.