Skip to content

Commit aeb0903

Browse files
JillGrant615JillGrant615
authored
Merge pull request #299211 from dlepow/dpevents
[APIM] Data plane events
2 parents 9de781b + 62d200e commit aeb0903

File tree

6 files changed

+165
-16
lines changed

6 files changed

+165
-16
lines changed

‎articles/api-management/backends.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -334,3 +334,4 @@ Include a JSON snippet similar to the following in your ARM template for a load-
334334
* Blog: [Using Azure API Management circuit breaker and load balancing with Azure OpenAI Service](https://techcommunity.microsoft.com/t5/fasttrack-for-azure/using-azure-api-management-circuit-breaker-and-load-balancing/ba-p/4041003)
335335
* Set up a [Service Fabric backend](how-to-configure-service-fabric-backend.yml) using the Azure portal.
336336
* Quickstart [Create a Backend Pool in Azure API Management using Bicep for load balance OpenAI requests](https://github.com/Azure-Samples/apim-lbpool-openai-quickstart)
337+
* See [Azure API Management as an Event Grid source](/azure/event-grid/event-schema-api-management) for information about Event Grid events that are generated by the gateway when a circuit breaker is tripped or reset. Use these events to take action before backend issues escalate.

‎articles/api-management/how-to-event-grid.md

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ author: dlepow
55
ms.topic: how-to
66
ms.service: azure-api-management
77
ms.author: danlep
8-
ms.date: 11/2/2021
8+
ms.date: 05/07/2025
99
ms.custom: devx-track-azurecli
1010
---
1111

@@ -15,12 +15,19 @@ ms.custom: devx-track-azurecli
1515

1616
API Management integrates with [Azure Event Grid](../event-grid/overview.md) so that you can send event notifications to other services and trigger downstream processes. Event Grid is a fully managed event routing service that uses a publish-subscribe model. Event Grid has built-in support for Azure services like [Azure Functions](../azure-functions/functions-overview.md) and [Azure Logic Apps](../logic-apps/logic-apps-overview.md), and can deliver event alerts to non-Azure services using webhooks.
1717

18+
You can subscribe to the following types of API Management events:
19+
20+
* **Control plane events**: These events are generated when you create, update, or delete certain API Management resources. For example, you can receive an event when a new user or new product is created in your API Management instance.
21+
* **Data plane events** (preview): These events are generated during operation of the API Management gateway. Currently, API Management can generate events for [backend circuit breakers](backends.md#circuit-breaker) and for the lifecycle of self-hosted gateway [access tokens](self-hosted-gateway-overview.md#authentication-options).
22+
23+
For a complete list of available events, see the [Event Grid schema for API Management](../event-grid/event-schema-api-management.md).
24+
25+
:::image type="content" source="media/how-to-event-grid/event-grid-intro.png" alt-text="Diagram of API Management integration with Event Grid.":::
26+
1827
For example, using integration with Event Grid, you can build an application that updates a database, creates a billing account, and sends an email notification each time a user is added to your API Management instance.
1928

2029
In this article, you subscribe to Event Grid events in your API Management instance, trigger events, and send the events to an endpoint that processes the data. To keep it simple, you send events to a sample web app that collects and displays the messages:
2130

22-
:::image type="content" source="media/how-to-event-grid/event-grid-viewer-intro.png" alt-text="API Management events in Event Grid viewer":::
23-
2431
[!INCLUDE [azure-cli-prepare-your-environment.md](~/reusable-content/azure-cli/azure-cli-prepare-your-environment.md)]
2532
- If you don't already have an API Management service, complete the following quickstart: [Create an Azure API Management instance](get-started-create-service-instance.md)
2633
- Enable a [system-assigned managed identity](api-management-howto-use-managed-service-identity.md#create-a-system-assigned-managed-identity) in your API Management instance.

‎articles/api-management/media/how-to-event-grid/event-grid-intro.png

91.7 KB
Loading

‎articles/api-management/media/how-to-event-grid/event-grid-viewer-intro.png

-126 KB
Binary file not shown.

‎articles/api-management/self-hosted-gateway-overview.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,10 @@ To authenticate the connection between the self-hosted gateway and the cloud-bas
134134
| [Microsoft Entra authentication](self-hosted-gateway-enable-azure-ad.md) | Configure one or more Microsoft Entra apps for access to gateway<br/><br/>Manage access separately per app<br/><br/>Configure longer expiry times for secrets in accordance with your organization's policies<br/><br/>Use standard Microsoft Entra procedures to assign or revoke user or group permissions to app and to rotate secrets<br/><br/> |
135135
| Gateway access token (also called authentication key) | Token expires every 30 days at maximum and must be renewed in the containers<br/><br/>Backed by a gateway key that can be rotated independently (for example, to revoke access) <br/><br/>Regenerating gateway key invalidates all access tokens created with it |
136136

137+
> [!TIP]
138+
> See [Azure API Management as an Event Grid source](/azure/event-grid/event-schema-api-management) for information about Event Grid events that are generated by a self-hosted gateway when a gateway access token is near expiry or has expired. Use these events to ensure that deployed gateways are always able to authenticate with their associated API Management instance.
139+
140+
137141
### Connectivity failures
138142

139143
When connectivity to Azure is lost, the self-hosted gateway is unable to receive configuration updates, report its status, or upload telemetry.

‎articles/event-grid/event-schema-api-management.md

Lines changed: 150 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: This article describes how to use Azure API Management as an Event
44
ms.topic: conceptual
55
author: spelluru
66
ms.author: spelluru
7-
ms.date: 06/15/2022
7+
ms.date: 05/01/2025
88
---
99

1010
# Azure API Management as an Event Grid source
@@ -26,23 +26,27 @@ API Management emits the following event types:
2626
| Microsoft.ApiManagement.ProductCreated | Raised when a product is created. |
2727
| Microsoft.ApiManagement.ProductUpdated | Raised when a product is updated. |
2828
| Microsoft.ApiManagement.ProductDeleted | Raised when a product is deleted. |
29-
| Microsoft.ApiManagement.ReleaseCreated | Raised when an API release is created. |
30-
| Microsoft.ApiManagement.ReleaseUpdated | Raised when an API release is updated. |
31-
| Microsoft.ApiManagement.ReleaseDeleted | Raised when an API release is deleted. |
29+
| Microsoft.ApiManagement.APIReleaseCreated | Raised when an API release is created. |
30+
| Microsoft.ApiManagement.APIReleaseUpdated | Raised when an API release is updated. |
31+
| Microsoft.ApiManagement.APIReleaseDeleted | Raised when an API release is deleted. |
3232
| Microsoft.ApiManagement.SubscriptionCreated | Raised when a subscription is created. |
3333
| Microsoft.ApiManagement.SubscriptionUpdated | Raised when a subscription is updated. |
3434
| Microsoft.ApiManagement.SubscriptionDeleted | Raised when a subscription is deleted. |
3535
| Microsoft.ApiManagement.GatewayCreated | Raised when a self-hosted gateway is created. |
3636
| Microsoft.ApiManagement.GatewayDeleted | Raised when a self-hosted gateway is updated. |
3737
| Microsoft.ApiManagement.GatewayUpdated | Raised when a self-hosted gateway is deleted. |
38-
| Microsoft.ApiManagement.GatewayAPIAdded | Raised when an API was removed from a self-hosted gateway. |
39-
| Microsoft.ApiManagement.GatewayAPIRemoved | Raised when an API was removed from a self-hosted gateway. |
40-
| Microsoft.ApiManagement.GatewayCertificateAuthorityCreated | Raised when a certificate authority was updated for a self-hosted. |
41-
| Microsoft.ApiManagement.GatewayCertificateAuthorityDeleted | Raised when a certificate authority was deleted for a self-hosted. |
42-
| Microsoft.ApiManagement.GatewayCertificateAuthorityUpdated | Raised when a certificate authority was updated for a self-hosted. |
43-
| Microsoft.ApiManagement.GatewayHostnameConfigurationCreated | Raised when a hostname configuration was created for a self-hosted. |
44-
| Microsoft.ApiManagement.GatewayHostnameConfigurationDeleted | Raised when a hostname configuration was deleted for a self-hosted. |
45-
| Microsoft.ApiManagement.GatewayHostnameConfigurationUpdated | Raised when a hostname configuration was updated for a self-hosted. |
38+
| Microsoft.ApiManagement.GatewayAPIAdded | Raised when an API is added to a self-hosted gateway. |
39+
| Microsoft.ApiManagement.GatewayAPIRemoved | Raised when an API is removed from a self-hosted gateway. |
40+
| Microsoft.ApiManagement.GatewayCertificateAuthorityCreated | Raised when a certificate authority is updated for a self-hosted gateway. |
41+
| Microsoft.ApiManagement.GatewayCertificateAuthorityDeleted | Raised when a certificate authority is deleted for a self-hosted gateway. |
42+
| Microsoft.ApiManagement.GatewayCertificateAuthorityUpdated | Raised when a certificate authority is updated for a self-hosted gateway. |
43+
| Microsoft.ApiManagement.GatewayHostnameConfigurationCreated | Raised when a hostname configuration is created for a self-hosted gateway. |
44+
| Microsoft.ApiManagement.GatewayHostnameConfigurationDeleted | Raised when a hostname configuration is deleted for a self-hosted gateway. |
45+
| Microsoft.ApiManagement.GatewayHostnameConfigurationUpdated | Raised when a hostname configuration is updated for a self-hosted gateway. |
46+
| Microsoft.ApiManagement.GatewayTokenNearExpiry (preview)| Raised when a self-hosted gateway access token is near expiry. |
47+
| Microsoft.ApiManagement.GatewayTokenExpired (preview) | Raised when a self-hosted gateway access token is expired. |
48+
| Microsoft.ApiManagement.CircuitBreaker.Opened (preview) | Raised when a backend circuit breaker is opened. |
49+
| Microsoft.ApiManagement.CircuitBreaker.Closed (preview) | Raised when a backend circuit breaker is closed. |
4650

4751
## Example event
4852

@@ -162,6 +166,113 @@ The following example shows the schema of an API updated event. The schema of ot
162166

163167
---
164168

169+
# [Cloud event schema](#tab/cloud-event-schema)
170+
171+
The following example shows the schema of a circuit breaker opened event.
172+
173+
```json
174+
{
175+
"source": "/subscriptions/{subscription-id}/resourceGroups/{your-rg}/providers/Microsoft.ApiManagement/service/{your-APIM-instance}",
176+
"subject": "/backends/{backend-name}/circuit-breaker/rules/{rule-name}",
177+
"type": "Microsoft.ApiManagement.CircuitBreaker.Opened",
178+
"time": "2025-04-02T00:47:47.8536532Z",
179+
"id": "92c502f2-a966-42a7-a428-d3b319844544",
180+
"data": {
181+
"backendName": "{backend-name}",
182+
"circuitBreaker": {
183+
"rules": {
184+
"{rule-name}": {
185+
"tripDuration": "00:00:01"
186+
}
187+
}
188+
}
189+
},
190+
"specVersion": "1.0"
191+
}
192+
```
193+
194+
195+
# [Event Grid event schema](#tab/event-grid-event-schema)
196+
197+
The following example shows the schema of a circuit breaker opened event. The schema of a circuit breaker closed event is similar.
198+
199+
```json
200+
{
201+
"id": "92c502f2-a966-42a7-a428-d3b319844544",
202+
"topic": "/subscriptions/{subscription-id}/resourceGroups/{your-rg}/providers/Microsoft.ApiManagement/service/{your-APIM-instance}",
203+
"subject": "/backends/{backend-name}/circuit-breaker/rules/{rule-name}",
204+
"data": {
205+
"backendName": "{backend-name}",
206+
"circuitBreaker": {
207+
"rules": {
208+
"{rule-name}": {
209+
"tripDuration": "00:00:01"
210+
}
211+
}
212+
}
213+
},
214+
"eventType": "Microsoft.ApiManagement.CircuitBreaker.Opened",
215+
"dataVersion": "1",
216+
"metadataVersion": "1",
217+
"eventTime": "2025-04-02T00:47:48.8269769Z"
218+
}
219+
```
220+
221+
---
222+
223+
# [Cloud event schema](#tab/cloud-event-schema)
224+
225+
The following example shows the schema of a gateway token expired event. The schema of a gateway token near expiry event is similar, but substitutes an `expiresAtUtc` property for the `expiredAtUtc` property.
226+
227+
```json
228+
{
229+
"source": "/subscriptions/{subscription-id}/resourceGroups/{your-rg}/providers/Microsoft.ApiManagement/service/{your-APIM-instance}",
230+
"subject": "/gateways/{gateway-name}/{instance-name}",
231+
"type": "Microsoft.ApiManagement.GatewayTokenExpired",
232+
"time": "2025-04-02T00:47:47.8536532Z",
233+
"id": "92c502f2-a966-42a7-a428-d3b319844544",
234+
"data": {
235+
"gatewayInfo": {
236+
"gatewayId": "{gateway-name}",
237+
"instanceId": "{instance-name}"
238+
},
239+
"tokenInfo": {
240+
"expiredAtUtc": "2025-02-25T08:56:00.0000000Z"
241+
}
242+
},
243+
"specVersion": "1.0"
244+
}
245+
246+
```
247+
248+
249+
# [Event Grid event schema](#tab/event-grid-event-schema)
250+
251+
The following example shows the schema of a gateway token expired event.
252+
253+
```json
254+
{
255+
"id": "92c502f2-a966-42a7-a428-d3b319844544",
256+
"topic": "/subscriptions/{subscription-id}/resourceGroups/{your-rg}/providers/Microsoft.ApiManagement/service/{your-APIM-instance}",
257+
"subject": "/gateways/{gateway-name}/{instance-name}",
258+
"data": {
259+
"gatewayInfo": {
260+
"gatewayId": "{gateway-name}",
261+
"instanceId": "{instance-name}"
262+
},
263+
"tokenInfo": {
264+
"expiredAtUtc": "2025-02-25T08:56:00.0000000Z"
265+
}
266+
},
267+
"eventType": "Microsoft.ApiManagement.GatewayTokenExpired",
268+
"dataVersion": "1",
269+
"metadataVersion": "1",
270+
"eventTime": "2025-04-02T00:47:48.8269769Z"
271+
}
272+
```
273+
274+
---
275+
165276
## Event properties
166277

167278

@@ -196,12 +307,38 @@ An event has the following top-level data:
196307

197308
---
198309

199-
The data object has the following properties:
310+
311+
### Data object properties
312+
313+
314+
#### Control plane events
315+
316+
The `data` object has the following properties for control plane events such as creating, updating, and deleting API Management resources.
200317

201318
| Property | Type | Description |
202319
| -------- | ---- | ----------- |
203320
| `resourceUri` | string | The fully qualified ID of the resource that the compliance state change is for, including the resource name and resource type. Uses the format, `/subscriptions/<SubscriptionID>/resourceGroups/<ResourceGroup>/Microsoft.ApiManagement/service/<ServiceName>/<ResourceType>/<ResourceName>` |
204321

322+
#### Circuit breaker events
323+
324+
The `data` object has the following properties for circuit breaker events.
325+
326+
327+
| Property | Type | Description |
328+
| -------- | ---- | ----------- |
329+
|`backendNme` | string | The name (ID) of the backend entity in which the circuit breaker is configured. |
330+
|`circuitBreaker` | object | The circuit breaker configured in the backend, consisting of a `rules` object specifying the rule that tripped the backed. The rule has a `tripDuration` property in hh:mm:ss format specifying the duration for which the circuit breaker is tripped.
331+
332+
#### Self-hosted gateway authentication token events
333+
334+
The `data` object has the following properties for self-hosted gateway authentication token events.
335+
336+
| Property | Type | Description |
337+
| -------- | ---- | ----------- |
338+
| `gatewayInfo` | object | The self-hosted gateway information, consisting of the following string properties:<br/><br/>* `gatewayId` - The fully qualified ID of the gateway resource<br/>* `instanceId` - Unique instance ID of the deployed gateway |
339+
| `tokenInfo` | object | The token information, consisting of one of the following properties in the provider's UTC time:<br/><br/>* `expiresAtUtc` - for `GatewayTokenNearExpiry` event, or<br/>* `expiredAtUtc` - for `GatewayTokenExpired` event |
340+
341+
205342
## Tutorials and how-tos
206343

207344
|Title |Description |

0 commit comments

Comments
 (0)