You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/api-management/api-management-howto-policies.md
+31-29Lines changed: 31 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
---
2
2
title: Policies in Azure API Management
3
-
description: Introduction to API Management policies, which change API behavior through configuration. Policy statements run sequentially on an API request or response.
3
+
description: Learn about API Management policies, which change API behavior through configuration. Policy statements run sequentially on an API request or response.
4
4
services: api-management
5
5
author: dlepow
6
6
@@ -9,24 +9,26 @@ ms.topic: concept-article
9
9
ms.date: 05/13/2025
10
10
ms.author: danlep
11
11
12
+
#customer intent: As an API publisher, I want to learn about API Management policies so that I can use them to change API behavior.
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](api-management-policies.md).
20
+
In Azure API Management, API publishers can change API behavior through configuration by 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 like authentication, rate limiting, caching, and transformation of requests or responses. For a complete list, see [API Management policy reference](api-management-policies.md).
19
21
20
22
Popular policies include:
21
23
22
-
* Format conversion from XML to JSON
23
-
* Call rate limiting to restrict the number of incoming calls from a developer
24
-
* Filtering requests that come from certain IP addresses
24
+
* Format conversion from XML to JSON.
25
+
* Call rate limiting to restrict the number of incoming calls from a developer.
26
+
* Filtering of requests that come from certain IP addresses.
25
27
26
28
27
-
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.
29
+
Policies are applied inside the gateway between the API consumer and the managed API. Although the gateway receives requests and forwards them, unaltered, to the underlying API, a policy can apply changes to both the inbound request and the outbound response.
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:
32
34
@@ -35,7 +37,7 @@ Policy definitions are simple XML documents that describe a sequence of statemen
35
37
36
38
For more information about configuring policies, see [Set or edit policies](set-edit-policies.md).
37
39
38
-
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.
40
+
The policy XML configuration is divided into `inbound`, `backend`, `outbound`, and `on-error` sections. This series of specified policy statements runs in order for a request and a response. Here's what it looks like:
39
41
40
42
```xml
41
43
<policies>
@@ -50,7 +52,7 @@ The policy XML configuration is divided into `inbound`, `backend`, `outbound`, a
50
52
<!-- statements to be applied to the response go here -->
51
53
</outbound>
52
54
<on-error>
53
-
<!-- statements to be applied if there is an error condition go here -->
55
+
<!-- statements to be applied if there's an error condition go here -->
54
56
</on-error>
55
57
</policies>
56
58
```
@@ -64,42 +66,42 @@ If an error occurs during the processing of a request:
64
66
* Execution jumps to the statements in the `on-error` section.
65
67
66
68
By placing policy statements in the `on-error` section, you can:
67
-
* Review the error using the `context.LastError` property.
68
-
* Inspect and customize the error response using the `set-body` policy.
69
+
* Review the error by using the `context.LastError` property.
70
+
* Inspect and customize the error response by using the `set-body` policy.
69
71
* Configure what happens if an error occurs.
70
72
71
73
For more information, see [Error handling in API Management policies](./api-management-error-handling-policies.md).
72
74
73
75
## Policy expressions
74
76
75
-
Unless the policy specifies otherwise, [policy expressions](api-management-policy-expressions.md) can be used as attribute values or text values in any of the API Management policies. A policy expression is either:
77
+
Unless the policy specifies otherwise, [policy expressions](api-management-policy-expressions.md) can be used as attribute values or text values in any of the API Management policies. A policy expression is one of the following:
76
78
77
-
*a single C# statement enclosed in `@(expression)`, or
78
-
*a multi-statement C# code block, enclosed in `@{expression}`, that returns a value
79
+
*A single C# statement enclosed in `@(expression)`
80
+
*A multi-statement C# code block, enclosed in `@{expression}`, that returns a value
79
81
80
82
Each expression has access to the implicitly provided `context` variable and an allowed subset of .NET Framework types.
81
83
82
84
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][Control flow] and [Set variable][Set variable].
83
85
84
86
## Scopes
85
87
86
-
API Management allows you to define policies at the following *scopes*, from most broad to most narrow:
88
+
API Management enables you to define policies at the following scopes, presented here from broadest to narrowest:
87
89
88
90
* Global (all APIs)
89
91
* Workspace (all APIs associated with a selected workspace)
90
92
* Product (all APIs associated with a selected product)
91
93
* API (all operations in an API)
92
-
* Operation (single operation in an API)
94
+
* Operation (a single operation in an API)
93
95
94
96
When configuring a policy, you must first select the scope at which the policy applies.
:::image type="content" source="media/api-management-howto-policies/policy-scopes.png" alt-text="Diagram that illustrates the five policy scopes." lightbox="media/api-management-howto-policies/policy-scopes.png":::
97
99
98
100
### Things to know
99
101
100
-
* For fine-grained control for different API consumers, you can configure policy definitions at more than one scope
101
-
* Not all policies are supported at each scope and policy section
102
-
* 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` element
102
+
* For fine-grained control for different API consumers, you can configure policy definitions at more than one scope.
103
+
* Not all policies are supported at each scope and policy section.
104
+
* 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` element.
103
105
* Policies 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.
In API Management, a [GraphQL resolver](configure-graphql-resolver.md) is configured using policies scoped to a specific operation type and field in a [GraphQL schema](graphql-apis-overview.md#resolvers).
116
+
In API Management, a [GraphQL resolver](configure-graphql-resolver.md) is configured with policies scoped to a specific operation type and field in a [GraphQL schema](graphql-apis-overview.md#resolvers).
115
117
116
-
* 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`](http-data-source-policy.md) policy with elements to specify a request to (and optionally response from) an HTTP data source.
117
-
* 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.
118
-
* The gateway evaluates a resolver-scoped policy *after* any configured `inbound` and `backend` policies in the policy execution pipeline.
118
+
* Currently, API Management supports GraphQL resolvers that specify either HTTP API, Azure Cosmos DB, or Azure SQL data sources. For example, configure a single [`http-data-source`](http-data-source-policy.md) policy with elements to specify a request to (and optionally response from) an HTTP data source.
119
+
* You can't include a resolver policy in policy definitions at other scopes, such as API, product, or all APIs. The policy also doesn't inherit policies configured at other scopes.
120
+
* The gateway evaluates a resolver-scoped policy after any configured `inbound` and `backend` policies in the policy execution pipeline.
119
121
120
122
For more information, see [Configure a GraphQL resolver](configure-graphql-resolver.md).
121
123
@@ -139,16 +141,16 @@ Example policy definition at API scope:
139
141
</policies>
140
142
```
141
143
142
-
In the example policy definition above:
143
-
* The `cross-domain` statement would execute first.
144
-
* The [`find-and-replace` policy](find-and-replace-policy.md)would execute after any policies at a broader scope.
144
+
In the preceding example policy definition:
145
+
* The `cross-domain` statement runs first.
146
+
* The [`find-and-replace` policy](find-and-replace-policy.md)runs after any policies at a broader scope.
145
147
146
148
>[!NOTE]
147
-
> 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.
149
+
> 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 will be applied.
148
150
149
151
### Use policy expressions to modify requests
150
152
151
-
The following example uses [policy expressions][Policy expressions] and the [`set-header`](set-header-policy.md) 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.
153
+
The following example uses [policy expressions][Policy expressions] and the [`set-header`](set-header-policy.md) policy to add user data to incoming requests. The added header includes the user ID that's associated with the subscription key in the request, and the region where the gateway processing the request is hosted.
Copy file name to clipboardExpand all lines: includes/api-management-policies-azure-copilot.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,10 +7,10 @@ ms.author: danlep
7
7
---
8
8
## Get Copilot assistance
9
9
10
-
Get AI assistance from Copilot to create and edit your API Management policy definitions. With Copilot, create and update policies that match your specific requirements without needing to know the XML syntax, and get explanations of existing policies. Copilot can also help you translate policies you might have configured in other API management solutions.
10
+
You can get AI assistance from Copilot to create and edit your API Management policy definitions. You can use Copilot to create and update policies that match your specific requirements without needing to know the XML syntax. You can also get explanations of existing policies. And Copilot can help you translate policies that you might have configured in other API management solutions.
11
11
12
-
*[Microsoft Copilot in Azure](/azure/copilot/author-api-management-policies?toc=%2Fazure%2Fapi-management%2Ftoc.json&bc=%2Fazure%2Fapi-management%2Fbreadcrumb%2Ftoc.json)- Offers policy authoring assistance with natural language prompts in the Azure portal. Author policies in API Management's policy editor, and ask Copilot to explain policy sections.
13
-
*[GitHub Copilot for Azure in VS Code](../articles/api-management/api-management-debug-policies.md)- Provides policy authoring assistance in Visual Studio Code, accelerating policy configuration when you use the [Azure API Management Extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-apimanagement&ssr=false#overview). Prompt Copilot Chat or Copilot Edits (preview) with natural language to create and refine policy definitions in place.
12
+
*[Microsoft Copilot in Azure](/azure/copilot/author-api-management-policies?toc=%2Fazure%2Fapi-management%2Ftoc.json&bc=%2Fazure%2Fapi-management%2Fbreadcrumb%2Ftoc.json)provides policy authoring assistance with natural language prompts in the Azure portal. You can author policies in the API Management policy editor and ask Copilot to explain policy sections.
13
+
*[GitHub Copilot for Azure in Visual Studio Code](../articles/api-management/api-management-debug-policies.md)provides policy authoring assistance in Visual Studio Code, accelerating policy configuration when you use the [Azure API Management Extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-apimanagement&ssr=false#overview). You can prompt Copilot Chat or Copilot Edits with natural language to create and refine policy definitions in place.
0 commit comments