Aspirerelease/17.0
Watch Aspire live streamsDocumentazioneProva Aspire

Azure API Management backends and pools

Questi contenuti non sono ancora disponibili nella tua lingua.

A backend in Azure API Management (APIM) is a reusable definition of a service that the gateway forwards requests to. A backend pool groups several backends so that APIM load balances across them. The Aspire Azure API Management hosting integration models these as AzureApiManagementBackendResource and AzureApiManagementBackendPoolResource children of the service, and an API selects one of them with WithBackend.

You don’t need to add a backend when you route an Aspire workload with AddApi, because that overload creates the backend for you. Use the APIs on this page when an API forwards to something else.

This page assumes the apim resource from Get started with Azure API Management.

Call AddBackend with a deferred URI. In C#, create the URI with ReferenceExpression.Create. In TypeScript, use the refExpr tagged template.

apphost.mts
import { refExpr } from './.aspire/modules/aspire.mjs';
const backend = await apim.addBackend("orders-backend", refExpr`https://orders.example.com`);
const ordersApi = await apim.addApiWithoutTarget("orders-api", "orders");
await ordersApi.withApiBackend(backend);

Pass an options object to AddBackend to configure the protocol, TLS validation, managed identity authentication, and a circuit breaker.

apphost.mts
import { AzureApiManagementBackendProtocol, refExpr } from './.aspire/modules/aspire.mjs';
const backend = await apim.addBackend(
"custom-backend",
refExpr`https://backend.example.com`,
{
options: {
protocol: AzureApiManagementBackendProtocol.Soap,
managedIdentityResource: "api://backend",
validateCertificateName: false,
circuitBreaker: {
name: "serverErrors",
failureCount: 3,
failureIntervalSeconds: 30,
tripDurationSeconds: 60,
statusCodeRanges: [{ minimum: 500, maximum: 599 }],
},
},
});

The backend options have these properties:

OptionDefaultDescription
TitleThe resource nameThe backend display title. It has 1 to 300 characters.
ProtocolHttpThe protocol to the backend: Http for HTTP or HTTPS, or Soap.
ValidateCertificateChaintrueWhether APIM validates the backend certificate chain.
ValidateCertificateNametrueWhether APIM validates the backend certificate host name.
ManagedIdentityResourceNoneThe Microsoft Entra resource URI that APIM requests a token for, such as https://storage.azure.com/. Leave it unset for anonymous or policy-defined authentication.
CircuitBreakerNoneThe circuit breaker rule.

The AddBackend method also accepts a backendName that sets the physical backend identifier in APIM. It defaults to the resource name, has at most 80 characters, can’t contain *, #, &, +, :, <, >, or ?, and must be unique across all backends and backend pools of the service.

TLS certificate-chain and host name validation are on by default. Turn them off only for a specific backend that can’t present a valid certificate.

When you set ManagedIdentityResource, the generated API policy includes an authentication-managed-identity statement for that resource URI. It selects APIM’s user-assigned managed identity explicitly by client ID, because APIM otherwise defaults to a system-assigned identity.

Generic backends don’t infer Azure role assignments, because the required role depends on the target service. Grant the APIM identity access to the target yourself. In C#, the identity is available as apim.Resource.Identity, and its principal ID is available as apim.Resource.PrincipalId. For more information about the identity, see Service configuration.

A circuit breaker stops APIM from sending requests to a backend that’s failing. Circuit breakers aren’t supported on the Consumption tier.

OptionDefaultDescription
NamedefaultThe rule name.
FailureCount1The number of failures within the interval that opens the circuit. Minimum 1.
FailureIntervalSeconds10The interval, in seconds, during which failures are counted. Minimum 1.
StatusCodeRangesNoneThe inclusive HTTP status-code ranges that count as failures. Each minimum is 200 to 599, each maximum is at least its minimum and at most 599, and a rule has at most 10 ranges.
TripDurationSeconds10How long, in seconds, the circuit stays open. Minimum 1.
AcceptRetryAfterfalseWhether APIM honors the backend’s Retry-After response header.

The specialized methods create a backend for a modeled Azure resource. Each one sets the URL, the managed identity resource URI, and the role assignment that the APIM identity needs.

MethodTargetManaged identity resourceRole granted to the APIM identityCircuit breaker
AddAzureOpenAIBackendAn Azure OpenAI deploymenthttps://cognitiveservices.azure.comCognitive Services OpenAI User on the accountOpens on HTTP 429 and honors Retry-After
AddFoundryBackendA Foundry deployment that uses the OpenAI formathttps://cognitiveservices.azure.comCognitive Services User on the accountOpens on HTTP 429 and honors Retry-After
AddBlobStorageBackendAn Azure Blob Storage resourcehttps://storage.azure.com/Storage Blob Data Reader on the storage accountNone

The Azure OpenAI and Foundry backends use the deployment URL {account endpoint}openai/deployments/{deployment name}. They aren’t supported on the Consumption tier, and AddFoundryBackend throws an InvalidOperationException for a deployment that doesn’t use the OpenAI format.

apphost.mts
const openai = await builder.addAzureOpenAI("openai");
const chat = await openai.addDeployment("chat", "gpt-4o", "2024-08-06");
const openAIBackend = await apim.addAzureOpenAIBackend("openai-backend", chat);
const storage = await builder.addAzureStorage("storage");
const blobs = await storage.addBlobs("blobs");
const blobBackend = await apim.addBlobStorageBackend("blob-backend", blobs);

The principal that runs aspire deploy needs Microsoft.Authorization/roleAssignments/write on each target account, for example through the User Access Administrator or Owner role. For more information about role assignments, see Azure role assignments.

A backend pool is a backend that load balances across its members. Create a pool with AddBackendPool, then add members with WithBackend in C# or addBackendPoolMember in TypeScript. Attach the pool to an API with WithBackend in C# or withApiBackendPool in TypeScript.

apphost.mts
import { refExpr } from './.aspire/modules/aspire.mjs';
const primary = await apim.addBackend("primary", refExpr`https://primary.example.com`);
const secondary = await apim.addBackend("secondary", refExpr`https://secondary.example.com`);
const pool = await apim.addBackendPool("backend-pool");
await pool.addBackendPoolMember(primary, { priority: 1, weight: 3 });
await pool.addBackendPoolMember(secondary, { priority: 1, weight: 1 });
const pooledApi = await apim.addApiWithoutTarget("pooled-api", "pooled");
await pooledApi.withApiBackendPool(pool);

Members at the same priority share traffic according to their weights, so the example sends about three of every four requests to primary. A lower priority number is preferred. APIM uses the members at the next priority when every member in the preferred group has an open circuit.

Aspire enforces these rules for pools:

  • Priority and weight are each 0 to 100, and both default to 1.
  • A pool has at most 30 members, and a backend can be added to a pool only once.
  • The pool and its members belong to the same APIM service.
  • All members use the same ManagedIdentityResource value. The API that uses the pool authenticates with that audience.
  • A pool contains at least one backend when you deploy.
  • The physical pool name follows the same rules as a backend name, and the displayName has 1 to 300 characters.

An API accepts either a single backend or a pool. The Azure OpenAI and Foundry backends include a circuit breaker by default. For generic backends, set CircuitBreaker if you want APIM to take a failing member out of rotation.

The following example balances an OpenAI-compatible API across two Foundry accounts. Each backend uses the managed identity of APIM, and each has a circuit breaker for HTTP 429 responses.

apphost.mts
const primaryFoundry = await builder.addFoundry("foundry-primary");
const primaryChat = await primaryFoundry.addDeployment("chat-primary", {
name: "gpt-5-mini",
version: "2025-08-07",
format: "OpenAI",
});
const secondaryFoundry = await builder.addFoundry("foundry-secondary");
const secondaryChat = await secondaryFoundry.addDeployment("chat-secondary", {
name: "gpt-5-mini",
version: "2025-08-07",
format: "OpenAI",
});
const primaryBackend = await apim.addFoundryBackend("primary-backend", primaryChat);
const secondaryBackend = await apim.addFoundryBackend("secondary-backend", secondaryChat);
const pool = await apim.addBackendPool("openai-pool");
await pool.addBackendPoolMember(primaryBackend, { priority: 1, weight: 3 });
await pool.addBackendPoolMember(secondaryBackend, { priority: 1, weight: 1 });
const openAIApi = await apim.addOpenAIApi("openai-api", "openai", {
subscriptionRequired: false,
});
await openAIApi.withApiBackendPool(pool);

A request through the gateway maps to the selected deployment. For example, a request such as:

POST https://<gateway>.azure-api.net/openai/chat/completions?api-version=<version>

is forwarded to the selected account at:

POST https://<account>/openai/deployments/<deployment>/chat/completions?api-version=<version>

The same pool model works with other services. This example shares traffic between two Blob Storage accounts and adds the x-ms-version header that the Blob Storage REST API expects:

apphost.mts
const primaryStorage = await builder.addAzureStorage("storage-primary");
const primaryBlobs = await primaryStorage.addBlobs("blobs-primary");
const secondaryStorage = await builder.addAzureStorage("storage-secondary");
const secondaryBlobs = await secondaryStorage.addBlobs("blobs-secondary");
const primaryBackend = await apim.addBlobStorageBackend("blob-primary", primaryBlobs);
const secondaryBackend = await apim.addBlobStorageBackend("blob-secondary", secondaryBlobs);
const pool = await apim.addBackendPool("blob-pool");
await pool.addBackendPoolMember(primaryBackend, { weight: 3 });
await pool.addBackendPoolMember(secondaryBackend);
const blobApi = await apim.addApiWithoutTarget("blob-api", "blobs");
await blobApi.withApiBackendPool(pool);
await blobApi.withInboundPolicy(
'<set-header name="x-ms-version" exists-action="override"><value>2023-11-03</value></set-header>');