What you need first
You need a provisioned Microsoft Foundry resource (created directly, or via a Foundry project that gives you the visual Studio tools). To connect from a client app you need the resource endpoint and an API key (from the Azure portal or the project home page), or the Foundry SDK with Entra ID.
Key concept · SDK and the required model deployments
Install the Python SDK with pip install azure-ai-contentunderstanding (Python 3.9+), or call the REST API from any HTTP-capable language. Critically, before using the API you must set up default model deployments for the resource: GPT-4.1, GPT-4.1-mini, and text-embedding-3-large — configured via the portal or the API.
A schema as JSON
Instead of the Studio UI, you can create an analyzer in code from a JSON definition.
Key concept · The analyzer definition
The JSON carries a description, a baseAnalyzerId (e.g. prebuilt-document), a config (e.g. returnDetails: true), a fieldSchema, and the models to use. Each field in fieldSchema.fields has a type (e.g. "string"), a method (extract to read existing values or generate to infer), and a description. A business-card analyzer, for example, defines ContactName and EmailAddress over prebuilt-document with GPT-4.1 and text-embedding-3-large.
Create it two ways: the SDK's begin_create_analyzer() (async, returns a poller), or a REST PUT to /analyzers/{name}, then poll the Operation-Location callback with GET until the status is no longer "Running."
Run it and read the fields
Submit content by URL or binary upload (PDF, PNG, MP3, MP4, …). The SDK — client.begin_analyze(analyzer_id, inputs=[AnalysisInput(url=…)]) then poller.result() — polls automatically; the REST path POSTs to {analyzer}:analyze, gets an operation ID, then GETs analyzerResults/{id} until "Succeeded."
Key concept · Reading typed results
Results depend on content type, schema, and file. For documents they include extracted fields with confidence scores, OCR layout, markdown, and page metadata — e.g. ContactName = "John Smith" at 0.994 confidence. Iterate result.contents[0].fields, checking each field's type (e.g. "string") before reading its value (SDK) or valueString (REST JSON). REST auth uses the Ocp-Apim-Subscription-Key header; API version 2025-11-01.
Chapter 28 quiz
Thirteen questions on setup, creating an analyzer, and analyzing. Answer first, then expand Show answer.
Part A · Multiple choice
Which model deployments are required before using the Content Understanding API?
- A GPT-4.1, GPT-4.1-mini, and text-embedding-3-large
- B Sora-2 only
- C Whisper and DALL·E
- D None
Show answer
A. Set up as default deployments on the resource.
Which Python package is the Content Understanding SDK?
- A azure-ai-contentunderstanding
- B azure-ai-textanalytics
- C azure-cognitiveservices-speech
- D openai
Show answer
A. Requires Python 3.9+.
In an analyzer definition, what does baseAnalyzerId specify?
- A The prebuilt analyzer to build on (e.g. prebuilt-document)
- B The billing account
- C The output filename
- D The Azure region
Show answer
A. The base to extend with your fieldSchema.
Which SDK method creates an analyzer?
- A begin_create_analyzer()
- B begin_analyze()
- C images.generate()
- D detect_language()
Show answer
A. Async, returning a poller.
How does the SDK's poller.result() handle the async operation?
- A It polls automatically until done
- B It returns immediately with no result
- C It requires a manual polling loop
- D It throws an error
Show answer
A. No manual polling loop needed.
Which header authenticates the REST API?
- A Ocp-Apim-Subscription-Key
- B X-Blob-Container-Url
- C Content-Length
- D Accept-Language
Show answer
A — Ocp-Apim-Subscription-Key.
Part B · True or false
A field's method can be either "extract" or "generate."
Show answer
True. Extract reads existing values; generate infers them.
Content can be submitted by URL or as binary file data.
Show answer
True. URL-based or analyzeBinary.
You should read a field's value without checking its type.
Show answer
False. Check the type (e.g. "string") first, then read value/valueString.
Document results can include OCR layout, markdown, and page metadata alongside fields.
Show answer
True. Plus confidence scores per field.
Part C · Short answer
Name three top-level keys in an analyzer JSON definition.
Show answer
Any three: description, baseAnalyzerId, config, fieldSchema, models.
What two credentials connect a client app to the API (key-based)?
Show answer
The resource endpoint and an API key (or Foundry SDK + Entra ID).
In the REST result, which property holds a string field's value?
Show answer
valueString (the SDK exposes it as value).