Aspirerelease/17.0
Watch Aspire live streamsDokumentationPrøv Aspire

Get started with Azure API Management

Dette indhold er ikke tilgængeligt i dit sprog endnu.

Azure logo

Azure API Management (APIM) is a managed gateway for publishing, securing, and observing APIs. The Aspire Azure API Management hosting integration models an APIM service and the resources beneath it, such as APIs, backends, policies, and products, as resources in your AppHost.

APIM is a deploy-only resource. Aspire omits it during aspire run and provisions it when you run aspire deploy, along with the APIs, backends, policies, and other resources that you declare beneath it. You don’t need an execution-mode guard in your AppHost.

To access the APIM types and APIs, add the 📦 Aspire.Hosting.Azure.ApiManagement NuGet package to your AppHost project. The package ships only prerelease versions, and the * version that most package references use selects only stable releases, so you must opt in to prerelease versions:

Aspire CLI — Add the Aspire.Hosting.Azure.ApiManagement package
aspire add azure-apimanagement --version <prerelease-version>

Replace <prerelease-version> with the latest prerelease version listed on NuGet. Alternatively, use a staging or dev quality CLI, which discovers prerelease packages without the --version option. For more information, see aspire add and the install script options.

The 17.0.0-* version range selects the latest 17.0 prerelease of the package.

The quickstart in the next section also uses an Azure Container Apps environment, which comes from a separate package:

Aspire CLI — Tilføj Aspire.Hosting.Azure.AppContainers-pakke
aspire add azure-appcontainers

Aspire CLI er interaktiv; vælg det passende søgeresultat når du bliver spurgt:

Aspire CLI — Eksempel output
Select an integration to add:
> azure-appcontainers (Aspire.Hosting.Azure.AppContainers)
> Other results listed as selectable options...

Call AddAzureApiManagement to add the service, then call AddApi with a compute resource to publish that workload through the gateway:

apphost.mts
import { createBuilder } from './.aspire/modules/aspire.mjs';
const builder = await createBuilder();
const environment = await builder.addAzureContainerAppEnvironment("env");
const catalog = await builder.addDotnetProject("catalog", "../Catalog/Catalog.csproj")
.withComputeEnvironment(environment)
.withExternalHttpEndpoints();
const apim = await builder.addAzureApiManagement("apim", {
publisherEmail: "api-owners@example.com",
publisherName: "Contoso APIs",
});
await apim.addApi("catalog-api", catalog, "catalog", {
subscriptionRequired: false,
});
await builder.build().run();

The preceding code:

  • Adds an Azure Container Apps environment. APIM routes to the workload’s deployed endpoint, so the workload needs an Azure compute environment when you publish or deploy.
  • Adds a catalog project that exposes external HTTP endpoints, which the APIM gateway can reach.
  • Adds an APIM service with the required publisher email and name. The service uses the Developer tier unless you set another SKU.
  • Publishes catalog at the catalog path of the gateway.

The compute-targeted AddApi overload creates an API, a reusable APIM backend, and catch-all operations that forward requests to the workload’s deployed endpoint. APIs require an APIM subscription key by default. The example sets subscriptionRequired to false so that you can call the gateway without a key. Keep the default for APIs that you don’t intend to expose anonymously, and see Products and subscriptions for how to issue keys.

APIM is omitted when you run aspire run, because a cloud-hosted APIM instance can’t reach a backend that runs on localhost, and Azure compute environments don’t materialize public endpoints in run mode. Your other resources continue to run locally as usual.

To provision the service and exercise its routing, deploy the AppHost:

Aspire CLI — Deploy the AppHost
aspire deploy

To generate the Bicep without deploying, use aspire publish. For more information, see Deploy to Azure and the aspire deploy command.

After deployment, call the gateway at https://<service-name>.azure-api.net/catalog, where <service-name> is the generated APIM service name. The gatewayUrl deployment output contains the gateway base URL.

Set Sku and Capacity on the options object that you pass to AddAzureApiManagement. Aspire validates the combination when you add the resource and throws an ArgumentException for an invalid capacity.

apphost.mts
import { AzureApiManagementSku, createBuilder } from './.aspire/modules/aspire.mjs';
const builder = await createBuilder();
const apim = await builder.addAzureApiManagement("apim", {
publisherEmail: "api-owners@example.com",
publisherName: "Contoso APIs",
sku: AzureApiManagementSku.StandardV2,
capacity: 2,
});
await builder.build().run();

The options have these properties:

OptionRequiredDefaultDescription
PublisherEmailYesNoneThe publisher email address that APIM shows. Maximum 100 characters.
PublisherNameYesNoneThe publisher name that APIM shows. Maximum 100 characters.
SkuNoDeveloperThe pricing tier.
CapacityNo0 for Consumption, otherwise 1The number of capacity units.

The integration supports the following tiers. Capacity is the range of scale units that Aspire accepts for the tier.

Sku valueCapacityNotes
Consumption0Serverless. Doesn’t support backend circuit breakers, Azure OpenAI and Foundry backends, or private endpoints. Supports one custom domain for the gateway endpoint only.
Developer1Non-production. Supports classic virtual network injection and multiple gateway custom domains.
Basic1 to 2Classic Basic tier.
BasicV21 to 10Doesn’t support private endpoints.
Standard1 to 4Classic Standard tier.
StandardV21 to 10Supports outbound virtual network integration.
Premium1 to 12Supports classic virtual network injection and multiple gateway custom domains.
PremiumV21 to 30Supports outbound virtual network integration, virtual network injection, and multiple gateway custom domains.

Tier capabilities differ substantially for networking, scale, availability zones, and multi-region deployment. For the full comparison, see API Management tier features. For networking requirements by tier, see Virtual networking.

The deployed service exposes the following outputs. They’re available as BicepOutputReference properties on the C# AzureApiManagementResource and aren’t projected to TypeScript AppHosts.

PropertyValue
NameOutputReferenceThe physical APIM service name (name output).
IdThe Azure resource ID of the service (id output).
GatewayUrlThe default gateway URL (gatewayUrl output).
PrincipalIdThe principal ID of the user-assigned managed identity that APIM uses.

The Identity property returns the user-assigned identity resource. For more information about how APIM uses it, see Service configuration.

The integration models the service as AzureApiManagementResource. Each part of the service is a child resource of that type:

Resource typeCreated byRepresents
AzureApiManagementApiResourceAddApi, AddOpenAIApiAn API published at a path on the gateway.
AzureApiManagementOperationResourceAddOperationAn explicitly modeled operation of an API.
AzureApiManagementBackendResourceAddBackend, AddAzureOpenAIBackend, AddFoundryBackend, AddBlobStorageBackendA reusable backend service.
AzureApiManagementBackendPoolResourceAddBackendPoolA weighted or priority-based group of backends.
AzureApiManagementPolicyFragmentResourceAddPolicyFragmentA reusable policy fragment.
AzureApiManagementNamedValueResourceAddNamedValue, AddSecretNamedValue, AddKeyVaultNamedValueA named value that policies can reference.
AzureApiManagementProductResourceAddProductA product that groups APIs.
AzureApiManagementSubscriptionResourceAddSubscriptionA product-scoped subscription.

Use ConfigureInfrastructure to customize the generated resources through the types in Azure.Provisioning.ApiManagement, such as ApiManagementService, ApiManagementApi, and ApiManagementBackend. For more information, see Customize Azure resources.

The integration creates a reverse proxy with configurable public ingress, and it accepts arbitrary APIM policy XML. Consider the following defaults and requirements:

  • APIs require an APIM subscription key unless you set subscriptionRequired to false.
  • Backend TLS certificate-chain and hostname validation are enabled by default. Disable them only for a specific backend that needs it.
  • Specialized Azure backends use APIM’s user-assigned managed identity and least-privilege service roles. For more information, see Backends and backend pools.
  • Creating role assignments requires Microsoft.Authorization/roleAssignments/write on each target scope. The principal that runs aspire deploy needs that permission, for example through the User Access Administrator or Owner role.
  • Key Vault-backed named values and certificates use the same user-assigned identity, so Aspire grants it only the Key Vault roles that it needs.

The integration doesn’t currently model the following capabilities:

  • Automatic disabling of public network access.
  • Backend client certificates and credential collections.
  • Consumer-safe references to subscription keys.
  • Structured gateway URL references.
  • Multi-region, availability zone, and autoscale configuration.
  • API versions and revisions.