Study guide
7.2 SDK and REST API Patterns
Azure AI Engineer Associate AI-102
Track your progress as you read
Finished sections get a check mark.
1 Introduction
About the Azure AI Engineer Associate (AI-102) Exam Study Strategies and Exam Tips for the AI-102
2 Domain 1: Plan and Manage an Azure AI Solution (20-25%)
1.1 Azure AI Services Overview and Selection 1.2 Resource Provisioning and Configuration 1.3 Security and Access Management 1.4 Responsible AI Principles and Implementation 1.5 Azure AI Solution Architecture Patterns
3 Content Safety and Moderation (within Plan and Manage, Domain 1)
2.1 Azure AI Content Safety Overview 2.2 Prompt Shields and Adversarial Attack Detection 2.3 Text and Image Moderation Implementation 2.4 Content Filtering in Azure OpenAI Service
4 Domain 4: Implement Computer Vision Solutions (10-15%)
3.1 Azure AI Vision — Image Analysis 4.0 3.2 Azure AI Face Service 3.3 Azure AI Custom Vision 3.4 Optical Character Recognition (OCR) 3.5 Video Analysis and the Retired Spatial Analysis
5 Domain 5: Implement Natural Language Processing Solutions (15-20%)
4.1 Azure AI Language — Text Analytics Features 4.2 Conversational Language Understanding (CLU) 4.3 Custom Text Classification and Custom NER 4.4 Azure AI Speech Services 4.5 Azure AI Translator Service 4.6 Question Answering and Conversational AI
6 Domain 6: Implement Knowledge Mining and Information Extraction Solutions (15-20%)
5.1 Azure AI Search — Fundamentals and Architecture 5.2 AI Enrichment with Skillsets 5.3 Azure AI Document Intelligence
7 Domain 2: Implement Generative AI Solutions (15-20%)
6.1 Azure OpenAI Service — Models and Deployment 6.2 Chat Completions API and Prompt Engineering 6.3 Embeddings and Vector Search for RAG 6.4 Fine-Tuning and Model Customization 6.5 Image Generation (gpt-image; DALL-E 3 Retired) 6.6 RAG After On Your Data, and AI Agents
8 Domain 3: Implement an Agentic Solution (5-10%)
3.1 Agentic Solutions: Foundry Agent Service and the Microsoft Agent Framework
9 Exam Review: Cross-Domain Topics and Advanced Practice
7.1 Service Comparison and Selection Guide 7.2 SDK and REST API Patterns 7.3 Responsible AI Across All Domains 7.4 End-to-End Solution Architectures 7.5 Exam Day Quick Reference
7.2 SDK and REST API Patterns
Key Takeaways Explain This Topic AI
Every Azure AI SDK follows the same shape: create a client from endpoint + credential, call a method, process the typed response.
Key auth uses the Ocp-Apim-Subscription-Key header; Entra ID auth uses Authorization: Bearer <token>; managed identity via DefaultAzureCredential is the production-preferred path.
Long-running operations (training, batch analyze, custom-model builds) return HTTP 202 with an Operation-Location header in REST, or a poller object in the SDK whose .result() blocks until done.
Memorize the distinct base URLs: most services use <resource>.cognitiveservices.azure.com, but Translator uses api.cognitive.microsofttranslator.com, AI Search uses <service>.search.windows.net, and Azure OpenAI uses <resource>.openai.azure.com.
Handle status codes deliberately: 401 (bad key/token), 403 (RBAC), 404 (endpoint), 429 (rate limit, back off using Retry-After), and content_filter errors from Azure OpenAI.
Last updated: June 2026
Quick Answer: Client = endpoint + credential, then call a method, then read a typed response. REST uses the Ocp-Apim-Subscription-Key header; Entra ID uses Authorization: Bearer . Async work returns 202 + Operation-Location (REST) or a poller (SDK). Handle 401, 403, 404, 429, and content_filter .
Universal SDK Pattern
The AI-102 expects you to read code, not write it from scratch. Every SDK uses the same three steps: from azure.ai.textanalytics import TextAnalyticsClient
- from azure.core.credentials import AzureKeyCredential
- from azure.identity import DefaultAzureCredential
- # Key-based auth
- client = TextAnalyticsClient(
- endpoint="https://my-res.cognitiveservices.azure.com/",
- credential=AzureKeyCredential("<key>"))
- # Production-preferred: managed identity / Entra ID
- client = TextAnalyticsClient(
- endpoint="https://my-res.cognitiveservices.azure.com/",
- credential=DefaultAzureCredential())
result = client.analyze_sentiment(["I love this product"])
for doc in result:
- print(doc.sentiment, doc.confidence_scores)
- Authentication Headers (REST)
- Method Header Notes
- API key Ocp-Apim-Subscription-Key: <key> Simplest; avoid in production
- Entra ID token Authorization: Bearer <token> Needs an RBAC role (e.g., Cognitive Services User)
Translator Ocp-Apim-Subscription-Key + Ocp-Apim-Subscription-Region Region header is required for multi-service keys
Azure OpenAI api-key: <key> or Authorization: Bearer Note: OpenAI uses api-key , not the Ocp-Apim header
Trap: Translator with a multi-service resource fails with 401 unless you also send Ocp-Apim-Subscription-Region . Azure OpenAI key auth uses the lowercase api-key header, not Ocp-Apim-Subscription-Key .
Service-Specific Endpoint Patterns
- Service Base URL pattern
- AI Vision / Language / Document Intelligence https://<resource>.cognitiveservices.azure.com/
- AI Translator https://api.cognitive.microsofttranslator.com/
- AI Speech https://<region>.api.cognitive.microsoft.com/
- AI Search https://<service>.search.windows.net/
- Azure OpenAI https://<resource>.openai.azure.com/openai/
Knowing which base URL belongs to which service is directly tested — Translator, Search, and OpenAI each break the common cognitiveservices.azure.com pattern.
- Long-Running Operations # SDK: begin_* returns a poller
- poller = client.begin_analyze_document(
- "prebuilt-invoice", body=file_bytes)
- result = poller.result() # blocks until 'succeeded'
In REST, the initial POST returns 202 Accepted with an Operation-Location header. You then GET that URL on an interval until status is succeeded (or failed ). Operations that use this pattern include Document Intelligence analyze, Language custom-model training, batch document translation, and Vision OCR for large files.
- Error Handling and Status Codes from azure.core.exceptions import (
- HttpResponseError, ClientAuthenticationError, ResourceNotFoundError)
try:
result = client.analyze_text(request)
except ClientAuthenticationError:
log("401: bad key or token")
except ResourceNotFoundError:
log("404: wrong endpoint or deployment")
except HttpResponseError as e:
if e.status_code == 429:
sleep(int(e.response.headers.get("Retry-After", 5)))
- Code Meaning Action
- 200 OK Process response
- 202 Accepted (async) Poll Operation-Location
- 400 Bad request Fix payload/parameters
- 401 Unauthorized Check key or token
- 403 Forbidden Grant the RBAC role
- 404 Not found Check endpoint/deployment name
- 429 Rate limited Exponential backoff, honor Retry-After
- 500/503 Service error Retry with backoff
On the Exam: A 429 is never solved by rotating the key — it means quota/TPM exhaustion, so back off or raise the quota. A content_filter finish reason from Azure OpenAI is not an error to retry blindly; it means the prompt or completion was blocked by the safety system.
Choosing Key Auth vs Entra ID vs Managed Identity
The SDK accepts any credential object, but the exam wants you to choose the right one for the scenario. Key auth ( AzureKeyCredential ) is fine for a quick prototype or a local script, but it embeds a long-lived secret that must be rotated and protected. Entra ID auth uses a short-lived bearer token and requires the caller to hold an RBAC role such as Cognitive Services User on the resource — choose it when the requirement mentions centralized identity, auditing, or eliminating shared keys.
Managed identity , surfaced through DefaultAzureCredential , is Entra ID with no secret at all: Azure issues and rotates the token for the app's system- or user-assigned identity. For any "production", "no secrets in code", or "App Service / Functions / VM" scenario, managed identity is the answer. DefaultAzureCredential is also convenient because it tries managed identity in Azure and falls back to developer credentials locally, so the same code works in both places.
Reading Responses and Confidence Scores
Many code questions hinge on what the response object contains, not on how the client was built. Language sentiment returns an overall label plus confidence_scores for positive, neutral, and negative that sum to 1.0 ; the exam may ask you to pick the label with the highest score. NER and PII return each entity with a category , a text offset and length , and a confidence_score you can threshold. Document Intelligence returns fields keyed by name, each with a value , a content string, and a confidence — production code typically routes anything below a configured confidence to human review.
Knowing that these scores exist, and that they are per-item rather than per-document, lets you eliminate options that claim a service returns only a single yes/no result.
Batch, Streaming, and Pagination Patterns
Azure AI APIs expose three throughput shapes you should recognize. Synchronous single-call APIs (sentiment on a short batch, a chat completion) return the full result immediately. Long-running operations (custom-model training, batch document translation, large-file OCR) return 202 and a poller, as covered above. Streaming applies to Azure OpenAI chat: setting stream=true returns server-sent event chunks so a UI can render tokens as they arrive instead of waiting for the whole completion.
Finally, list endpoints such as AI Search query results and Document Intelligence model lists are paginated — the SDK exposes an iterator that fetches the next page transparently, so you iterate rather than assuming one response holds every record. Matching the throughput shape to the workload is a recurring distractor theme.