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.
Add inbound policy statements
Section titled “Add inbound policy statements”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.
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>');apim.WithInboundPolicy(""" <set-header name="x-gateway" exists-action="override"> <value>Aspire</value> </set-header> """);
var catalogApi = apim.AddApi("catalog-api", catalog, path: "catalog") .WithInboundPolicy(""" <rate-limit calls="100" renewal-period="60" /> """);
catalogApi.AddOperation("get-product", "GET", "/products/{id}") .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:
| Scope | Generated policy |
|---|---|
| Service | An 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. |
| API | An 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. |
| Operation | An inbound section with base and your statements. The other sections contain base. |
Replace the complete policy
Section titled “Replace the complete policy”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.
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>`);var backend = apim.AddBackend( "orders-backend", ReferenceExpression.Create($"https://orders.example.com"));
apim.AddApi("orders-api", path: "orders") .WithBackend(backend) .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 ascatalog_apiBackend. WithPolicyandWithInboundPolicycan’t be combined at the same scope. Aspire throws anInvalidOperationExceptioninstead of silently discarding one of them.- The XML must be well-formed and must have a
policiesroot element.
Share statements with policy fragments
Section titled “Share statements with policy fragments”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.
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);var standardHeaders = apim.AddPolicyFragment( "standard-headers", """ <set-header name="x-powered-by" exists-action="override"> <value>Aspire</value> </set-header> """, description: "Headers shared by every API.");
apim.WithInboundPolicyFragment(standardHeaders);
var catalogApi = apim.AddApi("catalog-api", catalog, path: "catalog");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:
| Parameter | Required | Description |
|---|---|---|
name | Yes | The Aspire resource name. It’s also the default fragment identifier. |
policyXml | Yes | One or more well-formed policy elements without a fragment envelope. |
description | No | A description with at most 1,000 characters. |
fragmentName | No | The 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.
Add named values
Section titled “Add named values”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.
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>');apim.AddNamedValue("gateway-name", "Aspire");
var apiKey = builder.AddParameter("upstream-api-key", secret: true);apim.AddSecretNamedValue( "upstream-api-key-value", apiKey, displayName: "UpstreamApiKey");
var vault = builder.AddAzureKeyVault("vault");var sharedSecret = builder.AddParameter("shared-secret-value", secret: true);vault.AddSecret("vault-shared-secret", "shared-secret", sharedSecret);apim.AddKeyVaultNamedValue( "shared-secret", vault.GetSecret("shared-secret"), displayName: "SharedSecret");
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:
| Parameter | Description |
|---|---|
name | The Aspire resource name. It’s also the default physical named-value name. |
value | A string, a secret parameter, or a Key Vault secret. |
displayName | The name that policies use in {{name}}. Defaults to the resource name. It has 1 to 256 letters, digits, hyphens, periods, or underscores. |
namedValueName | The physical named-value identifier in APIM. Defaults to the resource name. |
tags | Tags that organize the named value. |
Aspire enforces these rules:
- A literal value isn’t empty or whitespace and has at most 4,096 characters.
AddSecretNamedValuerequires a parameter that’s marked as secret. Aspire throws anArgumentExceptionfor a parameter that isn’t.- The physical name and the display name are each unique within the service, ignoring case.
Key Vault-backed named values
Section titled “Key Vault-backed named values”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.