AI-200 Cheat Sheet

A manifest digest is a unique SHA-256 hash of the image's manifest, and every image or artifact, tagged or not, has its own, so referencing an image as repository@sha256:... always resolves to the exact same build even if a tag is later moved. Deploying by digest guarantees predictable, immutable image selection.

Trap Assuming a version-string tag is just as immutable as a digest.

An ACR tag, including a version-looking tag such as v1.2, can be repushed to point at a different manifest at any time, so deploying by tag does not guarantee a reproducible build.

The latest tag is simply the tag Docker and the registry assume when a command names none, so it moves only when a push actually carries it and not whenever any newer image is pushed. Because it is reused rather than unique it is a stable tag, and Microsoft's tagging guidance is to avoid deploying from stable tags because they keep receiving updates.

Trap Believing latest always points to the highest semantic version.

Best practice is to tag each build with a unique value such as a build ID or Git commit hash, so any deployed version is traceable and you can roll back to an exact, unchanged image.

A stable tag such as major.minor is deliberately re-pointed to the newest patched build so images that consume it pick up OS and framework fixes; it trades reproducibility for automatic patching and is typically used on base images, not deployments.

Running az acr repository update against one tag (--image myrepo:tag) or manifest digest (--image myrepo@sha256:...) sets that image's lock attributes: --write-enabled false makes it immutable so it can be neither overwritten nor deleted, while --delete-enabled false blocks only deletion and still allows the image to be updated. Locking a released production image protects it from accidental change.

Trap Assuming --delete-enabled false also stops the image from being overwritten.

az acr import pulls an image from another registry (Docker Hub, MCR, or another ACR) directly into the target registry, so it needs no local Docker daemon and no docker pull followed by docker push.

Trap Thinking the image has to be pulled locally and pushed again to land in the target registry.

Importing with source repository@sha256:... rather than by tag copies a specific immutable manifest, guaranteeing the imported image is byte-identical to the intended source build.

Trap Assuming az acr import only works with publicly accessible source images.

Removing or overwriting a tag does not delete the underlying manifest and layers; the resulting untagged (dangling) manifest keeps consuming registry storage until it is explicitly purged.

Trap Thinking that untagging an image reclaims its storage.

An acr purge command, usually run as a scheduled ACR Task, deletes tags that match a repository and tag regex (--filter) and are older than a duration (--ago), and by default it removes only the tag references, so --untagged is needed to delete the dangling manifests too. A Premium-tier retention policy is the filter-free alternative, automatically deleting every untagged manifest a set number of days after it becomes untagged.

Trap Expecting a plain acr purge to reclaim the manifests behind the tags it deleted.

When the soft-delete policy is enabled, deleted manifests and tags are retained for a configurable window and can be restored before they are permanently removed.

az acr build submits the build context to a quick task that builds the image on ACR-managed compute and pushes it to the registry, so no local Docker engine is required to produce and store an image.

Trap Assuming az acr build needs Docker installed on the developer machine.

az acr task run triggers an already-created task immediately, independent of its automatic triggers, which is useful for validating a task definition before wiring up commit or base-image triggers.

The positional argument of az acr build is the build context, which may be a local folder (uploaded as a tarball, honoring .dockerignore), a remote Git URL such as https://github.com/org/repo.git#branch:folder, or the URL of a remote tarball; -f/--file names the Dockerfile relative to that context rather than requiring it at the context root. --platform Linux/arm64 targets an architecture other than the default Linux/amd64, and --no-push compiles the image for validation without publishing it to the repository.

Trap Assuming the Dockerfile must sit at the root of the supplied context and be named exactly Dockerfile.

A base-image-update trigger tracks the image referenced in the Dockerfile FROM instruction and automatically rebuilds the dependent image whenever that base OS or runtime image is updated in the registry, enabling automated patching.

Trap Choosing a schedule trigger to react to base-image updates.

Base-image update triggers depend on the FROM instruction referencing a stable tag; if the Dockerfile pins its base image by digest, that base can never change and the trigger will never fire.

Trap Pinning the base image by digest and still expecting the base-image update trigger to fire.

Creating a task with a Git context registers a webhook on the linked GitHub or Azure Repos repository and rebuilds the image on each commit to the tracked branch, because --commit-trigger-enabled defaults to True. The pull-request trigger is a separate trigger on the same context and is disabled by default until you pass --pull-request-trigger-enabled true.

Trap Expecting a commit trigger to also react to base-image updates.

Creating a source-triggered task requires a Git personal access token so ACR can set the webhook and read the source repository. The required GitHub scopes depend on visibility: repo:status plus public_repo for a public repository, and full repo control for a private one; on Azure DevOps the required scope is Code (Read).

az acr task create --context https://github.com/org/repo.git#main:src binds the definition to exactly one branch (#main) and one subfolder (:src), so a push to any other branch is ignored even though the webhook exists. az acr task list-runs --registry --name then lists past executions with their TRIGGER column (Commit, Manual, Image Update, or Timer), which is how you confirm what actually started a given run.

Trap Expecting a task pinned to main to fire when a feature branch is pushed.

A scheduled (timer) trigger runs the task on a fixed cron schedule regardless of source or base-image changes, which suits periodic rebuilds or a recurring purge job but cannot guarantee a rebuild at the moment a dependency changes.

Trap Using a schedule trigger when the requirement is to rebuild exactly when a base image changes.

A multi-step task uses an acr-task.yaml file to run ordered build, push, and cmd steps (for example build the image, run tests, then push) within a single task execution.

The azure-cosmos CosmosClient is constructed from the account URI and a credential — either the account key/resource token or a Microsoft Entra token via DefaultAzureCredential. A single CosmosClient is thread-safe and should be created once and reused, because per-request clients waste connections and warm-up cost.

Trap Constructing a fresh CosmosClient per request instead of reusing one for the app's lifetime.

Passing DefaultAzureCredential authenticates with Entra ID, but reading or writing items also requires a Cosmos DB data-plane role assignment (for example Cosmos DB Built-in Data Reader or Data Contributor) scoped to the account. Azure RBAC management roles such as Contributor grant control-plane access only and do not authorize data operations.

Trap Owner/Contributor on the account does not grant data-plane read/write; you must assign a Cosmos DB built-in data role.

Gateway mode routes every request through the account's HTTPS gateway on port 443, which is firewall-friendly, while Direct mode opens TCP connections straight to backend replicas for lower latency and higher throughput. The .NET and Java SDKs support both modes; the Python and JavaScript SDKs operate in Gateway mode.

Trap Expecting to switch the Python SDK into Direct mode for lower latency.

Multi-region writes are enabled at the ACCOUNT level, and the client must then opt in as well. Microsoft's Python instruction is to set multiple_write_locations=True in the client initialization AND set preferred_locations to the regions the data is replicated into, ordered by preference: CosmosClient(url, credential, multiple_write_locations=True, preferred_locations=['West US','East US']). enable_endpoint_discovery defaults to True, so the SDK routes to the first available region in that list and falls back across regions on a regional event. You order the list yourself, shortest distance or best latency first; it is .NET's ApplicationRegion that auto-populates preferred locations by geo-proximity, not the Python argument.

Trap Enabling multiple write regions rules out Strong consistency (a multi-write account supports at most Bounded Staleness), and the conflict-resolution policy reconciles concurrent writes but does NOT do the region routing.

From a CosmosClient you obtain a DatabaseProxy via get_database_client(db_id) and a ContainerProxy via get_container_client(container_id); these proxies are lightweight client-side references to a named resource. Obtaining one does not confirm the resource is there: Microsoft describes a DatabaseProxy as an interface to a database that could, or couldn't, exist in the service yet, so a mistyped database or container name surfaces only when you call a real operation on the proxy.

Trap Treating a returned ContainerProxy as proof the container actually exists.

A container is created with a partition key path (for example /customerId), and each item's value at that path determines its logical partition. The SDK uses the partition key to route point reads and writes to the owning partition and to confine a query to a single physical partition when supplied.

Resource errors surface as typed exceptions — CosmosResourceNotFoundError for a missing item/container (HTTP 404) and CosmosResourceExistsError for a create conflict (HTTP 409) — so code branches on the exception type instead of parsing status codes. Convenience calls like create_container_if_not_exists absorb the 409.

Cosmos DB items carry a system _etag that changes on every write; to prevent a lost update, read the item, then issue a conditional replace passing that etag (the if-match request header, expressed in the current Python SDK as the etag keyword argument plus match_condition=MatchConditions.IfNotModified on replace_item or upsert_item). If another writer changed the item first, the server rejects the replace with HTTP 412 Precondition Failed and the app re-reads and retries. This is single-region item-level concurrency control, separate from the multi-region conflict-resolution policy.

read_item(item=id, partition_key=pk) performs a point read that retrieves one item directly from its partition, typically costing about 1 RU for a 1-KB document. When you know both the id and the partition key, a point read is always preferable to a query.

Trap SELECT * FROM c WHERE c.id=@id runs the query engine and costs more RUs than an equivalent point read.

container.query_items(query=..., parameters=...) executes a SQL query and returns a paged iterable of matching items. Queries engage the indexing and query engine and are billed per RU based on the work performed, which exceeds a point read when fetching a single known item.

Trap Reaching for query_items to fetch one item whose id and partition key are already known.

Supplying partition_key=value to query_items scopes execution to a single logical partition, which is cheaper and faster. Without it (or with enable_cross_partition_query=True in older SDKs) the query fans out to every physical partition, raising RU cost and latency.

Trap Omitting partition_key and still expecting the query to touch a single partition.

You author queries with @-prefixed placeholders and pass a parameters list of {"name": "@id", "value": v} entries to query_items, with the leading @ included in the name. Parameterization avoids string concatenation and is what provides robust handling and escaping of user input, preventing accidental exposure of data through SQL injection. Query plans are cached on the CLIENT, not by the service, keyed on the SQL query string, which is why an unparameterized query misses that cache; Microsoft documents the cache as enabled by default for the Java SDK 4.20.0+ and Spring Data 3.13.0+, and the documented Python lever for skipping the query-plan call is passing partition_key instead.

Trap Believing the service caches query plans, so a concatenated SQL string costs no more than a parameterized one.

The SDK runs a cross-partition query as parallel sub-queries per physical partition and merges results into pages; a continuation token resumes the next page after the client stops iterating. ORDER BY and aggregates across partitions require the SDK to gather and merge partial results, and in the Python SDK those are exactly the queries continuation tokens do NOT cover: cross-partition tokens are supported for streamable queries such as SELECT * FROM c WHERE ..., while aggregate cross-partition queries (sorting, counting, distinct) do not support continuation tokens. Separately, no SDK supports continuation tokens for GROUP BY, or for DISTINCT without an ORDER BY.

Trap Expecting a continuation token to resume a cross-partition ORDER BY or aggregate query in Python.

max_item_count on query_items is an upper bound on the items returned per page: the engine returns that number of items or fewer, never more. A page can therefore come back short, or even empty, when throttling, response size, execution time, or the engine's own efficiency choices split the results further, so correct code drains every page instead of trusting one round trip. The RU cost of each page is reported in the x-ms-request-charge response header (read in Python from container.client_connection.last_response_headers) so query cost can be measured and tuned.

A JOIN in Cosmos DB SQL unwinds arrays inside one document (intra-document), not rows across documents, and queries can project shaped results and call built-in functions such as STARTSWITH, ARRAY_CONTAINS, and VectorDistance.

A Request Unit abstracts the CPU, memory, and IOPS of an operation, so all reads, writes, and queries are charged in RUs against the container or database throughput. A point read of a 1-KB item is about 1 RU; writes and queries cost more depending on item size, indexed paths, and query complexity.

Every Cosmos response carries the RUs consumed in the x-ms-request-charge header, exposed through the SDK's response headers. Reading it is the authoritative way to profile and optimize a specific read, write, or query rather than estimating cost.

Trap Estimating an operation's RU cost from item size instead of reading x-ms-request-charge.

You allocate throughput at the database or container level as manual (fixed RU/s), autoscale (scales automatically between 10% and a configured maximum), or serverless (pay per consumed RU with no provisioning). Autoscale fits spiky or unpredictable traffic; serverless fits low, intermittent workloads.

A container's DefaultTimeToLive governs automatic expiry: a positive value is the default item lifetime in seconds, -1 enables TTL so only items carrying their own ttl expire, and null/absent disables it. Expired items disappear from queries immediately and are purged by a background task: on a provisioned throughput account that purge uses leftover RUs that user requests did not consume, while on a serverless account it is charged in RUs at the same rate as delete operations.

The integrated cache serves repeated point reads and identical queries from an in-memory cache on a provisioned dedicated gateway at effectively 0 RU — the lever for cutting RU on read-heavy repeat traffic. It requires connecting through the dedicated-gateway endpoint (gateway connection mode) with session or eventual consistency, and a MaxIntegratedCacheStaleness window bounds how stale a cached response may be.

When consumption exceeds the provisioned RU/s, Cosmos rejects the request with HTTP 429 (Request rate too large) and includes an x-ms-retry-after-ms header stating how long to wait before retrying. Sustained 429s indicate under-provisioned throughput or a hot partition.

By default the SDK transparently retries 429 responses, waiting the x-ms-retry-after-ms interval each time, up to a bounded number of attempts (nine by default, changed with the Python SDK's retry_total setting) and a maximum cumulative wait time (30 seconds by default, after which a CosmosHttpResponseError with status 429 reaches the application even if attempts remain). Raising these limits absorbs larger bursts at the cost of latency but does not add capacity.

Trap Increasing max retry attempts masks a hot partition or too-low RU/s; it does not provision more throughput.

Because throughput is divided across physical partitions, a partition key that concentrates traffic on one logical partition can trigger 429s while overall utilization looks low. The remedy is a higher-cardinality, evenly distributed partition key, not simply more RU/s.

The design rule for even throughput is to pick a partition key with high cardinality whose access pattern spreads work uniformly — a per-user or per-device id distributes load, whereas a low-cardinality field (a status flag) or a monotonically increasing timestamp concentrates writes and creates a hot partition. Because provisioned throughput divides evenly across a container's physical partitions and every logical partition maps to exactly one of them, a skewed key throttles one physical partition even when total account RUs are ample.

A container's indexing policy defaults to automatic, consistent indexing of all paths (/*). Write RU cost scales with the number of indexed paths, so excluding properties you never filter or sort on reduces write and storage cost without affecting the queries you actually run.

Trap Assuming properties you never filter or sort on are free because no query touches them.

Indexing paths use JSON path syntax: /* matches everything recursively, /category/? indexes the scalar at that path, and /metadata/* indexes a subtree. The most specific matching rule wins, so you can include /* while excluding a large subtree like /rawText/*.

Trap Assuming a broad /* include outranks a more specific excludedPaths entry.

indexingMode consistent (the default) updates the index synchronously as you create, update, or delete items, so read queries see the consistency configured for the account rather than a lagging index; none removes the index — suitable for a pure key/value point-read store where any query would otherwise scan. A third mode, lazy, can return inconsistent or incomplete query results and can no longer be selected for new containers.

Trap Setting indexingMode to none on a container that still has to answer queries.

Large properties such as embedding arrays or raw document text add write RU and storage when covered by the default index. Adding their path to excludedPaths while defining a dedicated vector index keeps writes cheap without losing the specialized search path.

A single-property range index handles ORDER BY on one field, but ordering by multiple properties (for example ORDER BY c.lastName ASC, c.firstName ASC) requires a compositeIndexes entry listing those paths with their sort orders, or the query fails.

Trap Expecting two single-property range indexes to satisfy an ORDER BY over both.

A composite index defined as (name ASC, age ASC) serves ORDER BY name ASC, age ASC and its exact reverse (name DESC, age DESC), but not (name ASC, age DESC). Define the composite index to mirror the query's property sequence and directions.

Trap Assuming one composite index serves every combination of sort directions on its properties.

Beyond multi-property ORDER BY, a composite index can reduce the RU charge of queries that filter on one property and range-filter or sort on another, because the engine resolves them from the composite index instead of a broader index scan.

The five levels — Strong, Bounded Staleness, Session, Consistent Prefix, and Eventual — trade read consistency against latency, availability, and RU cost. Session, the default, guarantees read-your-own-writes and monotonic reads within a client session and satisfies most applications.

Strong guarantees a linearizable, always-latest read but adds latency and is unavailable with multi-region writes; Bounded Staleness bounds lag by versions or time. Reads at Strong or Bounded Staleness cost about twice the RUs of Session, Consistent Prefix, or Eventual reads.

Trap Strong consistency is not compatible with multi-region (multi-master) write accounts.

Under Session consistency each write response returns a session token; to preserve read-your-own-writes across processes or nodes you capture that token and supply it on later requests' options. The token is produced by the operation response, not configured on the client.

Trap Hunting for the session token as a client setting instead of on the write response.

The account's default consistency applies to all requests, but an individual read may request a weaker level than the default (for example Eventual on a Strong account) to save RUs and latency. With the per-request ConsistencyLevel option that override can only relax consistency; moving to a level stronger than the account default means changing the account's own default.

When a multi-region write account takes concurrent writes to the same item in different regions, the container's conflict-resolution policy reconciles them: Last-Writer-Wins (the default, on a numeric/timestamp conflict path such as _ts) or a Custom policy backed by a merge stored procedure. The policy decides WHICH version wins; it does not route writes to the nearest region (that is the preferred-regions list).

To store embeddings you define a vector embedding policy at container creation listing each vector's path, dataType (for example float32), distanceFunction (cosine, dotproduct, or euclidean), and dimensions. The dimensions must equal the embedding model's output size, and the policy is set when the container is created.

Trap Planning to attach or change a vector embedding policy on a container that already exists.

The distanceFunction chosen in the embedding policy (cosine, dotproduct, euclidean) defines how VectorDistance ranks similarity, so it must align with the embedding model's recommended metric — for example cosine for normalized text embeddings. Mismatching it degrades retrieval relevance.

Trap Assuming any distance function ranks a given model's embeddings equally well.

A vector is a numeric array field on the document, co-located with the chunk text and its metadata (id, title, page). Storing them together lets one query return both the similarity ranking and the fields needed to ground and cite an answer.

Separate from the embedding policy, the indexing policy's vectorIndexes specifies a vector index type per path: flat (exact brute-force), quantizedFlat (compressed vectors for less storage and faster scan), or diskANN (graph-based approximate nearest neighbor for large collections).

Trap Assuming the vector embedding policy also creates the vector index.

flat computes exact distances by scanning every candidate vector — accurate but costly at scale. quantizedFlat still scans, but over quantized (compressed) vectors, cutting RU and latency at a small accuracy cost. diskANN builds a true graph-based approximate-nearest-neighbor index that scales to millions of vectors at low latency. Choose diskANN for very large collections, quantizedFlat for a mid-size compressed scan, and flat only for small sets or when exact recall is required.

Trap Choosing flat for a million-vector collection because it is the most accurate.

Because a raw embedding array is large, teams add its path to excludedPaths in the standard index to avoid needless write RU, while defining the vectorIndexes entry that actually powers similarity search on that same path.

The VectorDistance(c.embedding, @queryVector) system function returns the distance or similarity between a stored embedding and a supplied query vector using the container's configured metric, and can be projected as a score in the SELECT clause.

A query of the form SELECT TOP @k c.text, VectorDistance(c.embedding, @q) AS score FROM c ORDER BY VectorDistance(c.embedding, @q) returns the k most semantically similar items and engages the vector index for efficient nearest-neighbor retrieval - approximate on a diskANN index, exact on a flat one.

Trap VectorDistance in SELECT alone does not use the vector index for ranking; the ORDER BY VectorDistance clause is what drives the k-NN search.

You pass the query embedding as a query parameter (a numeric array) and project VectorDistance as an aliased score, letting the application rank matches and optionally drop results beyond a similarity threshold before sending context to the model.

To restrict semantic retrieval to a subset (for example one tenant or document category), add a WHERE clause on indexed metadata alongside ORDER BY VectorDistance. Cosmos applies the filter and returns the top-k nearest within that scope — the core metadata-filtered RAG pattern.

Because embeddings live in the same document as their source fields, the vector query projects document id, title, and page next to the score. The application uses that returned metadata to ground the generated answer and attach an accurate citation to each retrieved chunk.

Beyond pure vector search, Cosmos DB for NoSQL offers full-text search (for example FullTextScore) and hybrid queries that blend keyword and vector relevance using Reciprocal Rank Fusion (RRF), improving recall when lexical and semantic matches differ.

The change feed exposes items in the order they were modified within each logical partition, so downstream consumers can react to new or changed data. In its default mode it shows only the latest version of each changed item and does not surface deletes.

Trap Expecting the default change feed to replay every intermediate version of an item.

Latest-version (formerly incremental) mode returns the most recent state of changed items and no deletes. All-versions-and-deletes (full-fidelity) mode also emits deletes and intermediate versions, but it requires continuous backup / retention to be enabled on the account.

Trap Switching to all-versions-and-deletes mode on an account with no continuous backup enabled.

Because the default change feed does not emit hard deletes, a common pattern marks an item deleted with a flag (optionally with a TTL) so latest-version consumers see the update as a change. Use all-versions-and-deletes mode when true delete events must be captured.

The processor reads from the monitored (source) container, records progress in a separate lease container, runs on one or more compute instances (hosts), and invokes your delegate/handler with each batch of changes. All four pieces are required to build a processor.

Trap Expecting the processor to checkpoint into the monitored container without a separate lease container.

Each physical partition range gets a lease document in the lease container recording its continuation (checkpoint). Multiple host instances sharing the same lease container automatically balance partition ranges among themselves and resume from the last checkpoint after a restart.

Instances cooperate only as one deployment unit, which takes three things at once: the same lease container configuration, the same processor name, and a different instance name for each. Meet all three and the processor distributes every lease across the running instances using an equal-distribution algorithm and rebalances as instances come and go. A lease is owned by one instance at any time, so the number of instances shouldn't be greater than the number of leases, and a differing processor name builds a second deployment unit that reads the whole feed again instead of sharing the work.

Trap Expecting instances with different processor names to share the work rather than each read the whole feed.

The lease container is a separate container that acts as state storage and coordinates processing across workers; it can sit in the same account as the monitored container or in another account, and partitioned lease containers are required to have a /id partition key definition. It consumes its own request units for lease reads, writes and checkpoints, and throttling it delays change feed events or can end processing altogether. You normally provision it yourself, but the Azure Functions trigger can create it for you when CreateLeaseContainerIfNotExists is set to true (the default is false).

The processor advances the lease continuation (checkpoints) only after your delegate finishes a batch, so semantics are at-least-once: a host crash mid-batch causes the next owner to reprocess from the last checkpoint. Delegates must therefore be idempotent.

Trap Change feed processing is at-least-once, not exactly-once; make the handler idempotent to tolerate re-delivery.

When a lease is first created you can start reading from now (default — only future changes), from the container's beginning, or from a specific start time. Once a checkpoint exists the processor resumes from it and ignores the start setting.

Trap Setting start-from-beginning to re-read the feed when a lease checkpoint already exists.

Within a single logical partition the change feed preserves modification order, and the processor hands the delegate batches bounded by a max-items-per-page setting. Ordering is not guaranteed across different partition key ranges.

Trap Assuming the change feed delivers changes in one global order across every partition.

The change feed estimator compares each lease's checkpoint against the latest change to report the remaining backlog (estimated pending items). A growing estimate signals that consumers are falling behind and that more processor instances or throughput are needed.

The change feed processor is the push model: it polls, distributes leases, and invokes your delegate automatically. The pull model (query_items_change_feed with a continuation) gives manual control over which partition range and how much to read, but you must manage checkpoints yourself.

Trap Assuming the pull model manages leases and checkpoints the way the processor does.

The Azure Functions Cosmos DB trigger wraps the change feed processor: you supply the monitored container and a lease container, and the platform runs the processor and scales instances for you, making a Function the serverless way to consume the change feed.

A Service Bus queue is a point-to-point channel: many consumers can compete for messages, but each message is delivered to and processed by only one receiver. Choose a queue (not a topic) when a back-end operation must be handled exactly once by a single worker.

Trap A topic with multiple subscriptions is fan-out — each subscription gets its own copy — so it violates single-consumer delivery.

A Service Bus topic delivers a published message to every matching subscription, and each subscription is itself an independent queue read by its own consumer(s). Use topics + subscriptions when several independent consumers must each process the same event.

Each subscription can carry rules that filter the topic stream: a correlation filter matches system/application properties (fast, exact match), while a SQL filter evaluates a SQL-like expression over message properties. A subscription with no filter receives every message via the default TrueFilter.

Trap Assuming a subscription with no rule receives nothing until a filter is added.

In PeekLock mode the broker hands the message to one receiver and locks it for the lock duration; the receiver must call complete after successful work to remove it. This makes processing at-least-once and safe: a crash before Complete releases the lock so the message is redelivered.

Trap Treating a PeekLock receive as having already removed the message from the queue.

ReceiveAndDelete removes the message from the queue the instant it is delivered, before processing begins. It is faster and simpler but offers no retry: if the consumer crashes mid-work the message is gone. Use it only for high-throughput, loss-tolerant data.

Trap Reliable single-consumer processing needs PeekLock + Complete, never ReceiveAndDelete.

Beyond complete, the SDK exposes abandon (release the lock for immediate redelivery, incrementing the delivery count), dead_letter (move to the DLQ with a reason), and defer (set aside for later retrieval by sequence number). Each is an explicit settlement action only valid on a PeekLock message.

Trap Calling abandon or dead_letter on a message received in ReceiveAndDelete mode.

A PeekLock lock is held only for the entity's lock duration; long-running work must renew the lock (for example with an auto lock renewer) or the message unlocks and is redelivered. Repeated redeliveries eventually exceed the max delivery count.

Dead-lettered messages land in a dead-letter queue (DLQ), a secondary sub-queue belonging to the queue or topic subscription itself rather than a separate entity. It can't be deleted or managed independently of the main entity, messages can only be submitted to it via the dead-letter operation of the parent, time-to-live isn't observed there, and there's no automatic cleanup: messages stay until you receive and complete them. What you configure is the entity's dead-lettering settings, never the sub-queue itself.

Trap Expecting dead-lettered messages to age out of the DLQ on their own.

Service Bus moves a message to the DLQ automatically when it exceeds the max delivery count (repeated abandon/lock loss) or when its time-to-live expires with dead-lettering on expiration enabled. The application can also dead-letter a message explicitly (for example, a poison/unparseable payload).

Trap Expecting an expired message to reach the DLQ with dead-lettering on expiration switched off.

To inspect or reprocess dead-lettered messages you open a receiver against the sub-queue formatted as /$DeadLetterQueue (or /subscriptions/_{/$DeadLetterQueue). In the Python SDK this is done via the sub_queue=ServiceBusSubQueue.DEAD_LETTER option when creating the receiver.}

When a message is dead-lettered the broker (or app) records DeadLetterReason and DeadLetterErrorDescription in the message's application properties, letting an operator triage why delivery failed before reprocessing.

Enabling sessions on a queue/subscription groups messages by SessionId and locks an entire session to one receiver, guaranteeing first-in-first-out processing within that session. This is how you achieve ordered, related-message processing that a plain competing-consumer queue cannot.

Trap A session must be enabled at entity creation; you cannot get per-key ordering from a non-session queue just by setting SessionId.

To read a session-enabled entity you create a session receiver, which locks one session and delivers its messages in order. In Python there is no separate accept call: the session is chosen through the same receiver factory, either get_queue_receiver(queue_name=..., session_id="") for a named session or session_id=NEXT_AVAILABLE_SESSION to take whichever session is free. Session state can be persisted on the broker through the receiver's session object to checkpoint per-session progress.

Trap Hunting for a separate accept-session call in the Python SDK.

Each message has a time-to-live (defaulting to the entity's default TTL, capped by it); once it expires the message is removed, and if dead-lettering on message expiration is enabled it is moved to the DLQ instead of being silently dropped.

Trap Setting a per-message TTL longer than the entity's default and expecting it to hold.

A single ServiceBusClient (built from a namespace + DefaultAzureCredential or a connection string) is the entry point; you call get_queue_sender / get_queue_receiver (or the topic/subscription variants) to obtain a ServiceBusSender for publishing and a ServiceBusReceiver for consuming. Messages are ServiceBusMessage objects.

The event-driven ServiceBusProcessor (.NET) registers a message handler and an error handler and continuously pumps messages, auto-completing them on success unless auto-complete is disabled; the Python SDK achieves the same by iterating a ServiceBusReceiver and settling each message explicitly.

Trap Expecting the Python receiver to auto-complete messages the way the .NET processor does.

When duplicate detection is enabled on a queue/topic, the broker ignores any incoming message whose MessageId matches one seen within the configured detection history window (default 10 minutes, minimum 20 seconds, maximum 7 days). A suppressed send still reports success to the sender, and no part of the message other than the MessageId is considered, so the sender must set a stable, reconstructible MessageId for this to work.

Trap Expecting a send suppressed by duplicate detection to surface as an error.

A sender can schedule a message to become available at a future instant by setting its scheduled enqueue time (or calling schedule_messages), which returns a sequence number that can be used to cancel the scheduled delivery before it fires.

A custom (application) topic exposes an HTTPS endpoint to which your app POSTs events; the publisher authenticates with the topic's access key (or SAS token, or a managed identity with the EventGrid Data Sender role). This is how first-party app events enter Event Grid.

A custom event in the native Event Grid schema must supply id, subject, eventType, eventTime, and data (the payload). dataVersion is optional and is stamped with an empty value when omitted, while topic and metadataVersion are stamped by Event Grid. The subject and eventType are the fields most subscriptions filter on, so publishers set them deliberately to enable routing.

Trap Treating topic as a field the publisher has to populate on a custom event.

A topic can be configured to use the CloudEvents 1.0 schema (fields include specversion, type, source, id, time, subject, and data) for interoperability with other CloudEvents systems. The schema is set with two separate knobs, not one: the input schema is fixed when the topic is created (--input-schema), while the output (delivery) schema is chosen per event subscription (--event-delivery-schema). Event Grid input can be delivered as CloudEvents, but CloudEvents input cannot be delivered in the Event Grid schema, because CloudEvents extension attributes have no place in it.

Trap Assuming a single schema setting on the topic governs both input and delivery.

An event subscription can filter on the event's subject using subjectBeginsWith (for example a folder path prefix) and subjectEndsWith (for example a file extension), plus a case-sensitivity flag. This is the lightweight first-line filter for narrowing which events a handler receives.

Advanced filters evaluate a specific key inside the event (including data payload fields) with operators like StringIn, StringContains, NumberGreaterThan, and BoolEquals, allowing precise content-based routing beyond subject prefixes. Multiple advanced filters combine with AND semantics.

Trap Expecting multiple advanced filters to match when only one of them is satisfied.

A subscription can restrict delivery to a named list of event types via includedEventTypes; omitting it delivers all event types published to the topic. This is the coarsest, most common filter for custom-event workflows.

If a handler does not return success, Event Grid retries with an exponential back-off schedule until either the configured maximum delivery attempts or the event time-to-live is reached. Tuning these two retry-policy values controls how long a transient handler outage is tolerated.

Trap Raising max delivery attempts when the event time-to-live is what expires first.

When retries are exhausted, Event Grid writes the event to a dead-letter destination that is an Azure Storage blob container; the storage account and container must already exist before the subscription is created, and Event Grid names each blob after the subscription in upper case. Enabling a system- or user-assigned managed identity for dead-lettering is OPTIONAL, and only when one is enabled must that identity hold an RBAC role permitting writes to the storage. Storage queues are not a valid Event Grid dead-letter target.

Trap Expecting Event Grid to create the dead-letter storage container for you.

Certain HTTP responses from a webhook handler (for example 400 Bad Request or 413 Payload Too Large) are treated as non-retriable, so Event Grid stops retrying and, if dead-lettering is configured on the subscription, dead-letters the event right away; dead-lettering is off by default, and with no dead-letter destination configured the event is dropped instead. 5xx responses and timeouts are retried under the back-off policy.

When you create a subscription to a webhook that Azure does not validate automatically (which includes an HTTP-triggered Azure Function, not only endpoints outside Azure), Event Grid sends a SubscriptionValidationEvent containing a validationCode; the endpoint must echo that code back in a validationResponse (synchronous) or use the manual validationUrl handshake, proving ownership before delivery begins.

Trap Assuming an HTTP-triggered Azure Function is validated automatically because it lives in Azure.

A subscription's endpoint can be an Azure Function, Logic App, Service Bus queue/topic, Storage Queue, Event Hub, or an arbitrary HTTPS webhook. Azure-native handlers (like Functions with the Event Grid trigger) auto-complete the validation handshake, unlike a raw webhook.

When a subscription uses the CloudEvents 1.0 schema, endpoint validation follows the CloudEvents abuse-protection flow — an HTTP OPTIONS request carrying WebHook-Request-Origin that the endpoint answers with WebHook-Allowed-Origin — rather than echoing a validationCode.

Instantiate SecretClient(vault_url="https://.vault.azure.net", credential=DefaultAzureCredential()) and call get_secret(name) to read a secret at runtime; DefaultAzureCredential uses the app's managed identity in Azure and developer credentials locally, so no secret or connection string is embedded in code.

Trap Passing a raw API key or hard-coded credential to SecretClient defeats the purpose — the client is meant to be reached with a managed identity via DefaultAzureCredential.

A secret identifier without a version segment (.../secrets/), which Key Vault calls a base identifier, resolves to the latest version of the object, while appending a version (.../secrets//) pins that immutable version. get_secret with no version argument returns the latest version.

Trap Pinning a versioned URI means a rotated secret is NOT picked up; use the versionless identifier when you want rotation to flow through automatically.

The SDK exposes SecretClient for secrets, KeyClient for cryptographic keys, and CertificateClient for certificates; they are separate clients against the same vault endpoint because the three object types have distinct operations and permissions.

The exp and nbf attributes on a Key Vault secret are informational for a get - the docs carry a dedicated Date-time controlled operations section stating that a get works for not-yet-valid and expired secrets, so they can be used for test and recovery scenarios. Only enabled=false blocks a get. A get against a disabled version fails and the value cannot be read until the version is re-enabled with update_secret_properties(name, enabled=True).

Trap Setting an expiration date does not stop an application from reading the secret - code that must hard-stop access to a compromised credential has to DISABLE the secret version, not merely expire it.

Key Vault SDK clients for secrets, keys and certificates send their first request without an access token on purpose: Key Vault answers HTTP 401 with a WWW-Authenticate header naming the authorization endpoint and the resource, and the client then retries with a valid token. A 401 on a process's first Key Vault call is the expected handshake, not a misconfiguration; only a 401 that persists after the retry indicates a real credential or access problem.

Trap A 401 in traces or logs for the first Key Vault call does NOT mean DefaultAzureCredential failed - the handshake is how the client learns which tenant to authenticate against, so chasing it as a credential bug wastes the investigation.

A SecretClient is constructed against exactly one vault's data-plane endpoint, and the DNS suffix is cloud-specific (.vault.azure.net in the public cloud, .vault.azure.cn and .vault.usgovcloudapi.net in the sovereign clouds), so the vault URL must be configuration rather than a literal in code that runs across clouds. Managed HSM is a keys-only container reached at .managedhsm.azure.net: it supports HSM-protected keys and nothing else, so secret retrieval has no Managed HSM equivalent.

Trap Managed HSM is not a higher-security drop-in for a vault that stores secrets - it exposes only /keys, so a workload that must RETRIEVE secrets still needs a key vault no matter how strong its HSM requirement is.

Key Vault's transaction budget is enforced per vault per region and answers HTTP 429 once a client exceeds it, so a single high-traffic vault is the bottleneck rather than the subscription. Retrieval scales by caching secrets in memory and re-reading only when the cached copy stops working, and by splitting traffic across multiple vaults - but the subscription-wide ceiling is only five times a single vault's limit, so adding vaults inside one subscription stops helping.

Trap Retrying a 429 immediately does not help; and because the throttle scope is the vault resource, 'use a bigger vault' is not an available move - the levers are caching, more vaults, and eventually more subscriptions.

Key Vault publishes lifecycle events (Microsoft.KeyVault.SecretNearExpiry, SecretExpired, SecretNewVersionCreated) to Event Grid; subscribing an Azure Function to SecretNearExpiry lets you generate a new credential in the backing service and add it as a new secret version before the old one expires.

Trap Polling the vault on a timer to check expiry is the anti-pattern the event model replaces — rotation should be event-driven off SecretNearExpiry, not scheduled scanning.

Rotation does not overwrite in place; set_secret adds a new version and the prior version stays recoverable. Consumers that reference the secret by its versionless identifier begin resolving the new version automatically, which is what allows rotation without a redeploy.

Trap Thinking rotation overwrites the secret in place, so the previous value is gone.

For keys (not secrets), Key Vault offers a rotation policy that regenerates the key on a defined interval and can fire a near-expiry Event Grid notification; secret rotation of external credentials still relies on a custom rotation handler.

Set an App Service or Functions application setting to @Microsoft.KeyVault(SecretUri=) (or @Microsoft.KeyVault(VaultName=...;SecretName=...)); the platform resolves it from Key Vault using the app's managed identity and injects the plain value as an environment variable, so the secret never appears in source control or configuration files.

Trap The app's managed identity still needs Get permission on the vault (Key Vault Secrets User under RBAC); without it the reference FAILS TO RESOLVE and the platform injects the literal '@Microsoft.KeyVault(...)' reference string as the setting value — it is never blank.

When the reference omits the version, App Service periodically refreshes the resolved value (within about a day, or immediately on an application-settings change or restart) so a rotated secret flows in with no redeploy and no downtime; a versioned reference stays fixed to that version.

Trap Expecting a version-pinned Key Vault reference to follow a rotated secret.

Assign the app's system- or user-assigned managed identity the data-plane role Key Vault Secrets User (get/list secrets) scoped to the vault; the app then authenticates with that identity via DefaultAzureCredential and reads secrets with no stored credential.

Trap Key Vault Secrets User grants only read (get/list); creating or rotating secrets requires Key Vault Secrets Officer — don't over- or under-grant the role.

Each vault's permission model is set by enableRbacAuthorization: Azure RBAC uses role assignments that inherit from subscription/resource-group scope, while the legacy vault-access-policy model assigns per-principal permissions on the vault itself. Microsoft recommends RBAC for consistent, scopeable management.

Trap Expecting a leftover vault access policy to still grant access once the vault moves to Azure RBAC.

DefaultAzureCredential tries an ordered chain of credentials - environment variables, then workload/managed identity, then developer credentials (Azure CLI / VS Code) - so the same SDK code authenticates locally and in Azure with no code change. Configuration is what differs: when the workload must authenticate as a USER-ASSIGNED managed identity, name it by client id (the AZURE_CLIENT_ID environment variable, or ManagedIdentityCredential(client_id=...)), because IMDS resolves an unnamed request to the system-assigned identity when one is enabled and rejects it outright when several user-assigned identities exist.

Trap Supplying no client id does NOT reliably fail: with a system-assigned identity enabled, IMDS defaults to it, so a role granted only to a user-assigned identity produces a 403 authorization error rather than an authentication error. The request fails outright only when no system-assigned identity is enabled and two or more user-assigned identities exist.

Soft-delete (enabled by default and not disableable) keeps a deleted vault or secret in a recoverable state for its configured retention period; you recover the object during that window instead of losing it permanently.

Trap Assuming soft-delete can be switched off to make a delete immediate.

With purge protection enabled, a soft-deleted vault or secret cannot be purged (permanently deleted) before its retention period ends, defeating an attacker or accident that tries to erase secrets immediately. Purge protection cannot be turned off once enabled.

Trap Soft-delete alone still allows an immediate purge; only purge protection prevents early permanent deletion — the two settings are distinct.