Policies in Azure API Management
APPLIES TO: All API Management tiers
In Azure API Management, API publishers can change API behavior through configuration using policies. Policies are a collection of statements that are run sequentially on the request or response of an API. API Management provides more than 50 policies out of the box that you can configure to address common API scenarios such as authentication, rate limiting, caching, and transformation of requests or responses. For a complete list, see API Management policy reference.
Popular policies include:
- Format conversion from XML to JSON
- Call rate limiting to restrict the number of incoming calls from a developer
- Filtering requests that come from certain IP addresses
Policies are applied inside the gateway between the API consumer and the managed API. While the gateway receives requests and forwards them, unaltered, to the underlying API, a policy can apply changes to both the inbound request and outbound response.
Understanding policy configuration
Policy definitions are simple XML documents that describe a sequence of statements to apply to requests and responses. To help you configure policy definitions, the portal provides these options:
- A guided, form-based editor to simplify configuring popular policies without coding XML
- A code editor where you can insert XML snippets or edit XML directly
For more information about configuring policies, see Set or edit policies.
The policy XML configuration is divided into inbound
, backend
, outbound
, and on-error
sections. This series of specified policy statements is executed in order for a request and a response.
<policies>
<inbound>
<!-- statements to be applied to the request go here -->
</inbound>
<backend>
<!-- statements to be applied before the request is forwarded to
the backend service go here -->
</backend>
<outbound>
<!-- statements to be applied to the response go here -->
</outbound>
<on-error>
<!-- statements to be applied if there is an error condition go here -->
</on-error>
</policies>
For policy XML examples, see API Management policy snippets repo.
Error handling
If an error occurs during the processing of a request:
- Any remaining steps in the
inbound
,backend
, oroutbound
sections are skipped. - Execution jumps to the statements in the
on-error
section.
By placing policy statements in the on-error
section, you can:
- Review the error using the
context.LastError
property. - Inspect and customize the error response using the
set-body
policy. - Configure what happens if an error occurs.
For more information, see Error handling in API Management policies.
Policy expressions
Unless the policy specifies otherwise, policy expressions can be used as attribute values or text values in any of the API Management policies. A policy expression is either:
- a single C# statement enclosed in
@(expression)
, or - a multi-statement C# code block, enclosed in
@{expression}
, that returns a value
Each expression has access to the implicitly provided context
variable and an allowed subset of .NET Framework types.
Policy expressions provide a sophisticated means to control traffic and modify API behavior without requiring you to write specialized code or modify backend services. Some policies are based on policy expressions, such as Control flow and Set variable.
Scopes
API Management allows you to define policies at the following scopes, from most broad to most narrow:
- Global (all APIs)
- Workspace (all APIs associated with a selected workspace)
- Product (all APIs associated with a selected product)
- API (all operations in an API)
- Operation (single operation in an API)
When configuring a policy, you must first select the scope at which the policy applies.
Things to know
For fine-grained control for different API consumers, you can configure policy definitions at more than one scope
Not all policies are supported at each scope and policy section
When configuring policy definitions at more than one scope, you control policy inheritance and the policy evaluation order in each policy section by placement of the
base
elementPolicies applied to API requests are also affected by the request context, including the presence or absence of a subscription key used in the request, the API or product scope of the subscription key, and whether the API or product requires a subscription.
Note
If you're using an API-scoped subscription, an all-APIs subscription, or the built-in all-access subscription, policies configured at the product scope aren't applied to requests from that subscription.
For more information, see:
GraphQL resolver policies
In API Management, a GraphQL resolver is configured using policies scoped to a specific operation type and field in a GraphQL schema.
- Currently, API Management supports GraphQL resolvers that specify either HTTP API, Cosmos DB, or Azure SQL data sources. For example, configure a single
http-data-source
policy with elements to specify a request to (and optionally response from) an HTTP data source. - You can't include a resolver policy in policy definitions at other scopes such as API, product, or all APIs. It also doesn't inherit policies configured at other scopes.
- The gateway evaluates a resolver-scoped policy after any configured
inbound
andbackend
policies in the policy execution pipeline.
For more information, see Configure a GraphQL resolver.
Get assistance creating policies using Microsoft Copilot in Azure (preview)
Microsoft Copilot in Azure (preview) provides policy authoring capabilities for Azure API Management. Use Copilot in Azure in the context of API Management's policy editor to create policies that match your specific requirements without knowing the syntax, or have already configured policies explained to you.
You can prompt Copilot in Azure to generate policy definitions, then copy the results into the policy editor and make any necessary adjustments. Ask questions to gain insights into different options, modify the provided policy, or clarify the policy you already have. Learn more
Examples
Apply policies specified at different scopes
If you have a policy at the global level and a policy configured for an API, both policies can be applied whenever that particular API is used. API Management allows for deterministic ordering of combined policy statements via the base
element.
Example policy definition at API scope:
<policies>
<inbound>
<cross-domain />
<base />
<find-and-replace from="xyz" to="abc" />
</inbound>
</policies>
In the example policy definition above:
- The
cross-domain
statement would execute first. - The
find-and-replace
policy would execute after any policies at a broader scope.
Note
If you remove the base
element at the API scope, only policies configured at the API scope will be applied. Neither product nor global scope policies would be applied.
Use policy expressions to modify requests
The following example uses policy expressions and the set-header
policy to add user data to the incoming request. The added header includes the user ID associated with the subscription key in the request, and the region where the gateway processing the request is hosted.
<policies>
<inbound>
<base />
<set-header name="x-request-context-data" exists-action="override">
<value>@(context.User.Id)</value>
<value>@(context.Deployment.Region)</value>
</set-header>
</inbound>
</policies>
Related content
For more information about working with policies, see:
- Tutorial: Transform and protect your API
- Policy reference for a full list of policy statements and their settings
- Policy expressions
- Set or edit policies
- Reuse policy configurations
- Policy snippets repo
- Author policies using Microsoft Copilot in Azure
Phản hồi
https://aka.ms/ContentUserFeedback.
Sắp ra mắt: Trong năm 2024, chúng tôi sẽ dần gỡ bỏ Sự cố với GitHub dưới dạng cơ chế phản hồi cho nội dung và thay thế bằng hệ thống phản hồi mới. Để biết thêm thông tin, hãy xem:Gửi và xem ý kiến phản hồi dành cho