Aspirerelease/17.0

API Management products and subscriptions

Цей контент ще не доступний вашою мовою.

A product in Azure API Management (APIM) groups one or more APIs and controls how consumers get access to them. A subscription gives a consumer the keys that call the APIs in a product. The Aspire Azure API Management hosting integration models these as AzureApiManagementProductResource and AzureApiManagementSubscriptionResource children of the service.

This page assumes the apim and catalog resources from Get started with Azure API Management.

Call AddProduct to create a product, WithApi to add APIs to it, and AddSubscription to provision a subscription that’s scoped to the product.

apphost.mts
const catalogApi = await apim.addApi("catalog-api", catalog, "catalog");
const product = await apim.addProduct("catalog-product", "Catalog", {
options: {
description: "Catalog APIs",
subscriptionRequired: true,
approvalRequired: false,
},
});
await product.withApi(catalogApi);
await product.addSubscription("catalog-client", "Catalog client");

A product can contain only APIs from the same APIM service. Aspire provisions product membership as an API link on the product, which references the full resource ID of the API.

The AddProduct method has the following parameters:

ParameterRequiredDescription
nameYesThe Aspire resource name. It’s also the default physical product name.
displayNameYesThe product display name. It has at most 300 characters.
optionsNoThe product options.
productNameNoThe physical product identifier in APIM. It defaults to the resource name, has at most 256 characters, can’t contain *, #, &, +, :, <, >, or ?, and is unique within the service.

The product options have these properties:

OptionDefaultDescription
DescriptionNoneThe product description. It has at most 1,000 characters.
TermsNoneThe terms of use that subscribers see.
SubscriptionRequiredtrueWhether callers need a subscription to use the APIs in the product.
ApprovalRequiredfalseWhether subscription requests need administrator approval. It requires SubscriptionRequired.
SubscriptionsLimitNoneThe maximum number of subscriptions a user can create for the product. It must be greater than zero and requires SubscriptionRequired. When unset, the number is unlimited.
StatePublishedPublished makes the product visible to subscribers. NotPublished hides it.

Aspire throws an ArgumentException when you combine ApprovalRequired or SubscriptionsLimit with SubscriptionRequired set to false.

The following example creates a product for partners that requires approval, limits subscriptions, and stays unpublished until you publish it:

apphost.mts
import { AzureApiManagementProductState } from './.aspire/modules/aspire.mjs';
await apim.addProduct("partner-product", "Partner", {
options: {
description: "APIs for partners.",
terms: "Use of these APIs is subject to the partner agreement.",
approvalRequired: true,
subscriptionsLimit: 5,
state: AzureApiManagementProductState.NotPublished,
},
});

The AddSubscription method has the following parameters:

ParameterRequiredDescription
nameYesThe Aspire resource name. It’s also the default physical subscription name.
displayNameYesThe subscription display name. It has at most 100 characters.
optionsNoThe subscription options.
subscriptionNameNoThe physical subscription identifier in APIM. It defaults to the resource name, has at most 256 characters, and is unique across all products of the service.

The subscription options have these properties:

OptionDefaultDescription
AllowTracingfalseWhether tracing is allowed for the subscription.
StateActiveThe subscription state: Active, Suspended, Submitted, Rejected, Expired, or Cancelled.

APIM generates the primary and secondary keys for a subscription during deployment. Aspire intentionally doesn’t expose them as deployment outputs, because they’re secrets. Retrieve the keys from the Azure portal or through the APIM management API.

By default, callers send the key in the Ocp-Apim-Subscription-Key request header or in the subscription-key query string parameter.

An API that you add with subscriptionRequired set to true, which is the default, rejects requests without a valid key. The API-level and product-level subscription settings are separate properties in APIM. For how APIM combines them, see Subscriptions in Azure API Management.