Aspirerelease/17.0

API Management policies and named values

Это содержимое пока не доступно на вашем языке.

Policies change how Azure API Management (APIM) processes requests and responses, for example to limit rates, set headers, or rewrite URLs. The Aspire Azure API Management hosting integration lets you add policy statements at the service, API, and operation scope, share statements through policy fragments, and reference configuration values through named values.

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

Call WithInboundPolicy to append one or more policy statements to the inbound section at a scope. The method exists on the service, on APIs, and on operations.

apphost.mts
await apim.withInboundPolicy(
'<set-header name="x-gateway" exists-action="override"><value>Aspire</value></set-header>');
const catalogApi = await apim.addApi("catalog-api", catalog, "catalog");
await catalogApi.withInboundPolicy('<rate-limit calls="100" renewal-period="60" />');
const getProduct = await catalogApi.addOperation("get-product", "GET", "/products/{id}");
await getProduct.withInboundPolicy(
'<set-header name="x-operation" exists-action="override"><value>get-product</value></set-header>');

Each call appends statements in call order. The value must be one or more well-formed policy elements without a policies envelope. Aspire throws an ArgumentException if the XML is malformed or contains a complete policies document.

Aspire composes the policy document for each scope:

ScopeGenerated policy
ServiceAn inbound section with your statements, a forward-request backend section, and empty outbound and on-error sections. The service policy is the root of the hierarchy, so it has no base element.
APIAn inbound section with base, the authentication-managed-identity statement when the backend uses managed identity, set-backend-service, and then your statements. The other sections contain base.
OperationAn inbound section with base and your statements. The other sections contain base.

Call WithPolicy when you need full control of a policy document. The value must be a complete document with a policies root element. APIM replaces the whole policy at that scope.

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);
await ordersApi.withPolicy(`<policies>
<inbound>
<base />
<set-backend-service backend-id="orders-backend" />
<rate-limit calls="50" renewal-period="60" />
</inbound>
<backend><base /></backend>
<outbound><base /></outbound>
<on-error><base /></on-error>
</policies>`);

Keep the following in mind when you replace a policy:

  • Replacing an API policy also replaces the backend routing that Aspire generates. Your document must set the backend if the API should keep forwarding requests. The backend ID of a standalone backend is its physical name, which defaults to the resource name.
  • For an API that targets a compute resource, the generated backend ID is the API resource name with hyphens replaced by underscores, followed by Backend, such as catalog_apiBackend.
  • WithPolicy and WithInboundPolicy can’t be combined at the same scope. Aspire throws an InvalidOperationException instead of silently discarding one of them.
  • The XML must be well-formed and must have a policies root element.

A policy fragment is a reusable set of policy statements. Define it once with AddPolicyFragment, then include it at the service, API, or operation scope with WithInboundPolicyFragment.

apphost.mts
const standardHeaders = await apim.addPolicyFragment(
"standard-headers",
`<set-header name="x-powered-by" exists-action="override">
<value>Aspire</value>
</set-header>`,
{ description: "Headers shared by every API." });
await apim.withInboundPolicyFragment(standardHeaders);
const catalogApi = await apim.addApi("catalog-api", catalog, "catalog");
await catalogApi.withInboundPolicyFragment(standardHeaders);

Aspire wraps the statements in a fragment element and adds an include-fragment statement to the inbound policy at the scope where you include it. APIM deploys the policies after the fragments that they reference.

The AddPolicyFragment method has the following parameters:

ParameterRequiredDescription
nameYesThe Aspire resource name. It’s also the default fragment identifier.
policyXmlYesOne or more well-formed policy elements without a fragment envelope.
descriptionNoA description with at most 1,000 characters.
fragmentNameNoThe physical fragment identifier in APIM. Defaults to the resource name.

The fragment identifier has at most 80 characters. It can contain letters, digits, underscores, and hyphens, but it can’t start or end with a hyphen. Each identifier is unique within the service, and a policy can include only fragments from its own service.

Named values are configuration entries that policies reference with the {{name}} syntax. Aspire supports three kinds:

  • A literal value, for non-secret configuration.
  • A secret parameter, for a value that you supply through external parameters.
  • A Key Vault secret, which APIM reads from Azure Key Vault at run time.
apphost.mts
await apim.addNamedValue("gateway-name", "Aspire");
const apiKey = await builder.addParameter("upstream-api-key", { secret: true });
await apim.addSecretNamedValue("upstream-api-key-value", apiKey, {
displayName: "UpstreamApiKey",
});
const vault = await builder.addAzureKeyVault("vault");
const sharedSecret = await builder.addParameter("shared-secret-value", { secret: true });
await vault.addSecret("vault-shared-secret", sharedSecret, { secretName: "shared-secret" });
await apim.addKeyVaultNamedValue("shared-secret", vault, "shared-secret", {
displayName: "SharedSecret",
});
await apim.withInboundPolicy(
'<set-header name="x-powered-by" exists-action="override"><value>{{gateway-name}}</value></set-header>');

In the Key Vault example, the shared-secret-value secret parameter supplies the value, and AddSecret (addSecret in TypeScript) creates the shared-secret secret in the vault. APIM resolves a Key Vault-backed named value from a secret that already exists, so create the secret as shown or reference a vault that already contains it.

In TypeScript, addKeyVaultNamedValue takes the Key Vault resource and the secret name as separate arguments. In C#, you pass the Key Vault secret reference that GetSecret returns.

The named value methods share these parameters:

ParameterDescription
nameThe Aspire resource name. It’s also the default physical named-value name.
valueA string, a secret parameter, or a Key Vault secret.
displayNameThe name that policies use in {{name}}. Defaults to the resource name. It has 1 to 256 letters, digits, hyphens, periods, or underscores.
namedValueNameThe physical named-value identifier in APIM. Defaults to the resource name.
tagsTags that organize the named value.

Aspire enforces these rules:

  • A literal value isn’t empty or whitespace and has at most 4,096 characters.
  • AddSecretNamedValue requires a parameter that’s marked as secret. Aspire throws an ArgumentException for a parameter that isn’t.
  • The physical name and the display name are each unique within the service, ignoring case.

APIM reads a Key Vault-backed value through the user-assigned managed identity of the service. Aspire grants that identity the Key Vault Secrets User role on the vault through the standard Azure role-assignment pipeline, and the APIM deployment waits for the role assignment. The secret reference is versionless, so APIM picks up rotated values. For a Key Vault resource that isn’t an Azure provisioning resource, Aspire keeps an inline role assignment instead.

For an existing APIM service, supply an identity that’s already attached to the service. For more information, see Service configuration.