Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 5e1567c

Browse files
curibcurib
committedDec 10, 2020
Event Grid documentation
1 parent 52a7922 commit 5e1567c

File tree

4 files changed

+331
-0
lines changed

4 files changed

+331
-0
lines changed
 

‎articles/azure-cache-for-redis/cache-event-grid-quickstart.md

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
title: Send Azure Cache for Redis events to web endpoint - Azure CLI
3+
description: Use Azure Event Grid to subscribe to Azure Cache for Redis events. Send the events to a Webhook. Handle the events in a web application.
4+
author: curib
5+
ms.author: cauribeg
6+
ms.date: 12/08/2020
7+
ms.topic: how-to
8+
ms.service: cache
9+
---
10+
11+
# Quickstart: Route Azure Cache for Redis events to web endpoint with Azure CLI
12+
13+
Azure Event Grid is an eventing service for the cloud. In this article, you use the Azure CLI to subscribe to Azure Cache for Redis events, and trigger the event to view the result.
14+
15+
Typically, you send events to an endpoint that processes the event data and takes actions. However, to simplify this article, you send the events to a web app that collects and displays the messages.
16+
17+
When you complete the steps described in this article, you see that the event data has been sent to the web app.
18+
19+
![Screenshot of the Azure Event Grid Viewer that shows event data that has been sent to the web app.](./media/storage-blob-event-quickstart/view-results.png)
20+
21+
[!INCLUDE [quickstarts-free-trial-note.md](../../../includes/quickstarts-free-trial-note.md)]
22+
23+
[!INCLUDE [cloud-shell-try-it.md](../../../includes/cloud-shell-try-it.md)]
24+
25+
If you choose to install and use the CLI locally, this article requires that you're running the latest version of Azure CLI (2.0.70 or later). To find the version, run `az --version`. If you need to install or upgrade, see [Install Azure CLI](/cli/azure/install-azure-cli).
26+
27+
If you aren't using Cloud Shell, you must first sign in using `az login`.
28+
29+
## Create a resource group
30+
31+
Event Grid topics are Azure resources, and must be placed in an Azure resource group. The resource group is a logical collection into which Azure resources are deployed and managed.
32+
33+
Create a resource group with the [az group create](/cli/azure/group) command.
34+
35+
The following example creates a resource group named `<resource_group_name>` in the *westcentralus* location. Replace `<resource_group_name>` with a unique name for your resource group.
36+
37+
```azurecli-interactive
38+
az group create --name <resource_group_name> --location westcentralus
39+
```
40+
41+
## Create a cache
42+
43+
[!INCLUDE [redis-cache-create](../../includes/redis-cache-create.md)]
44+
45+
## Create a message endpoint
46+
47+
Before subscribing to the topic, let's create the endpoint for the event message. Typically, the endpoint takes actions based on the event data. To simplify this quickstart, you deploy a [pre-built web app](https://github.com/Azure-Samples/azure-event-grid-viewer) that displays the event messages. The deployed solution includes an App Service plan, an App Service web app, and source code from GitHub.
48+
49+
Replace `<your-site-name>` with a unique name for your web app. The web app name must be unique because it's part of the DNS entry.
50+
51+
```azurecli-interactive
52+
sitename=<your-site-name>
53+
54+
az group deployment create \
55+
--resource-group <resource_group_name> \
56+
--template-uri "https://raw.githubusercontent.com/Azure-Samples/azure-event-grid-viewer/master/azuredeploy.json" \
57+
--parameters siteName=$sitename hostingPlanName=viewerhost
58+
```
59+
60+
The deployment may take a few minutes to complete. After the deployment has succeeded, view your web app to make sure it's running. In a web browser, navigate to: `https://<your-site-name>.azurewebsites.net`
61+
62+
You should see the site with no messages currently displayed.
63+
64+
[!INCLUDE [event-grid-register-provider-cli.md](../../../includes/event-grid-register-provider-cli.md)]
65+
66+
## Subscribe to your Azure Cache for Redis account
67+
68+
You subscribe to a topic to tell Event Grid which events you want to track and where to send those events. The following example subscribes to the storage account you created, and passes the URL from your web app as the endpoint for event notification. Replace `<event_subscription_name>` with a name for your event subscription. For `<resource_group_name>` and `<storage_account_name>`, use the values you created earlier.
69+
70+
The endpoint for your web app must include the suffix `/api/updates/`.
71+
72+
```azurecli-interactive
73+
storageid=$(az storage account show --name <storage_account_name> --resource-group <resource_group_name> --query id --output tsv)
74+
endpoint=https://$sitename.azurewebsites.net/api/updates
75+
76+
az eventgrid event-subscription create \
77+
--source-resource-id $storageid \
78+
--name <event_subscription_name> \
79+
--endpoint $endpoint
80+
```
81+
82+
View your web app again, and notice that a subscription validation event has been sent to it. Select the eye icon to expand the event data. Event Grid sends the validation event so the endpoint can verify that it wants to receive event data. The web app includes code to validate the subscription.
83+
84+
![View subscription event](./media/storage-blob-event-quickstart/view-subscription-event.png)
85+
86+
## Trigger an event from Azure Cache for Redis
87+
88+
Now, let's trigger an event to see how Event Grid distributes the message to your endpoint. First, let's configure the name and key for the storage account, then we create a container, then create and upload a file. Again, use the values for `<storage_account_name>` and `<resource_group_name>` you created earlier.
89+
90+
```azurecli-interactive
91+
export AZURE_STORAGE_ACCOUNT=<storage_account_name>
92+
export AZURE_STORAGE_ACCESS_KEY="$(az storage account keys list --account-name <storage_account_name> --resource-group <resource_group_name> --query "[0].value" --output tsv)"
93+
94+
az storage container create --name testcontainer
95+
96+
touch testfile.txt
97+
az storage blob upload --file testfile.txt --container-name testcontainer --name testfile.txt
98+
```
99+
100+
You've triggered the event, and Event Grid sent the message to the endpoint you configured when subscribing. View your web app to see the event you just sent.
101+
102+
103+
```json
104+
[{
105+
"topic": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myrg/providers/Microsoft.Storage/storageAccounts/myblobstorageaccount",
106+
"subject": "/blobServices/default/containers/testcontainer/blobs/testfile.txt",
107+
"eventType": "Microsoft.Storage.BlobCreated",
108+
"eventTime": "2017-08-16T20:33:51.0595757Z",
109+
"id": "4d96b1d4-0001-00b3-58ce-16568c064fab",
110+
"data": {
111+
"api": "PutBlockList",
112+
"clientRequestId": "d65ca2e2-a168-4155-b7a4-2c925c18902f",
113+
"requestId": "4d96b1d4-0001-00b3-58ce-16568c000000",
114+
"eTag": "0x8D4E4E61AE038AD",
115+
"contentType": "text/plain",
116+
"contentLength": 0,
117+
"blobType": "BlockBlob",
118+
"url": "https://myblobstorageaccount.blob.core.windows.net/testcontainer/testblob1.txt",
119+
"sequencer": "00000000000000EB0000000000046199",
120+
"storageDiagnostics": {
121+
"batchId": "dffea416-b46e-4613-ac19-0371c0c5e352"
122+
}
123+
},
124+
"dataVersion": "",
125+
"metadataVersion": "1"
126+
}]
127+
128+
```
129+
130+
## Clean up resources
131+
If you plan to continue working with this storage account and event subscription, do not clean up the resources created in this article. If you do not plan to continue, use the following command to delete the resources you created in this article.
132+
133+
Replace `<resource_group_name>` with the resource group you created above.
134+
135+
```azurecli-interactive
136+
az group delete --name <resource_group_name>
137+
```
138+
139+
## Next steps
140+
141+
Now that you know how to create topics and event subscriptions, learn more about Blob storage Events and what Event Grid can help you do:
142+
143+
- [Reacting to Azure Cache for Redis events](cache-event-grid.md)
144+
- [About Event Grid](../event-grid/overview.md)

‎articles/azure-cache-for-redis/cache-event-grid.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: Azure Cache for Redis Event Grid Overview
3+
description: Use Azure Event Grid to publish Azure Cache for Redis events.
4+
author: curib
5+
ms.author: cauribeg
6+
ms.date: 12/08/2020
7+
ms.topic: conceptual
8+
ms.service: cache
9+
---
10+
11+
# Publishing Azure Cache for Redis events
12+
13+
Azure Cache for Redis events allows applications to react to patching, scaling, import/export (RDB) events.
14+
15+
Azure Cache for Redis events are pushed using [Azure Event Grid](https://azure.microsoft.com/services/event-grid/) to subscribers such as Azure Functions, Azure Logic Apps, or even to your own http listener. Event Grid provides reliable event delivery to your applications through rich retry policies and dead-lettering.
16+
17+
See the [Azure Cache for Redis events schema]() article to view the full list of the events that Azure Cache for Redis supports.
18+
19+
If you want to try Azure Cache for Redis events, see the following [quickstart]() article.
20+
21+
## The event model
22+
23+
Event Grid uses [event subscriptions](../../event-grid/concepts.md#event-subscriptions) to route event messages to subscribers. This image illustrates the relationship between event publishers, event subscriptions, and event handlers.
24+
25+
:::image type="content" source="media/cache-event-grid/event-grid-model.png" alt-text="Event grid model.":::
26+
27+
First, subscribe an endpoint to an event. Then, when an event is triggered, the Event Grid service will send data about that event to the endpoint.
28+
29+
See the [Azure Cache for Redis events schema]() article to view:
30+
31+
> [!div class="checklist"]
32+
> * A complete list of Azure Cache for Redis events and how each event is triggered.
33+
> * An example of the data the Event Grid would send for each of these events.
34+
> * The purpose of each key value pair that appears in the data.
35+
36+
37+
## Practices for consuming events
38+
39+
Applications that handle Azure Cache for Redis events should follow a few recommended practices:
40+
> [!div class="checklist"]
41+
> * As multiple subscriptions can be configured to route events to the same event handler, it is important not to assume events are from a particular source, but to check the topic of the message to ensure that it comes from the Azure Cache for Redis instance you are expecting.
42+
> * Similarly, check that the eventType is one you are prepared to process, and do not assume that all events you receive will be the types you expect.
43+
> * Azure Cache for Redis events guarantees at-least-once delivery to subscribers, which ensures that all messages are outputted. However due to retries or availability of subscriptions, duplicate messages may occasionally occur. To learn more about message delivery and retry, see [Event Grid message delivery and retry](../../event-grid/delivery-and-retry.md).
44+
45+
46+
## Next steps
47+
48+
Learn more about Event Grid and give Azure Cache for Redis events a try:
49+
50+
- [About Event Grid](../event-grid/overview.md)
51+
- [Azure Cache for Redis events schema](../event-grid/event-schema-azure-cache.md)
52+
- [Route Azure Cache for Redis events to a custom web endpoint](cache-event-grid-quickstart.md)

‎articles/azure-cache-for-redis/media/cache-event-grid/event-grid-model.png

131 KB
Loading

‎articles/event-grid/event-schema-azure-cache.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Azure Cache for Redis as Event Grid source
3+
description: Describes the properties that are provided for Azure Cache for Redis events with Azure Event Grid
4+
ms.topic: conceptual
5+
ms.date: 07/07/2020
6+
---
7+
8+
# Azure Cache for Redis as an Event Grid source
9+
10+
This article provides the properties and schema for Azure Cache for Redis events. For an introduction to event schemas, see [Azure Event Grid event schema](event-schema.md).
11+
12+
## Event Grid event schema
13+
14+
### List of events for Azure Cache for Redis REST APIs
15+
16+
These events are triggered when a client exports, imports, or scales by calling Azure Cache for Redis REST APIs. Patching event is triggered by Redis update.
17+
18+
|Event name |Description|
19+
|----------|-----------|
20+
|**Microsoft.Cache.ExportRDBCompleted** |Triggered when cache data is exported. |
21+
|**Microsoft.Cache.ImportRDBCompleted** |Triggered when cache data is imported. |
22+
|**Microsoft.Cache.PatchingCompleted** |Triggered when patching is completed. |
23+
|**Microsoft.Cache.ScalingCompleted** |Triggered when scaling is completed. |
24+
25+
<a name="example-event"></a>
26+
### The contents of an event response
27+
28+
When an event is triggered, the Event Grid service sends data about that event to subscribing endpoint.
29+
30+
This section contains an example of what that data would look like for each Azure Cache for Redis event.
31+
32+
### Microsoft.Cache.ScalingCompleted event
33+
34+
```json
35+
[{
36+
"id":"9b87886d-21a5-4af5-8e3e-10c4b8dac73b",
37+
"eventType":"Microsoft.Cache.ScalingCompleted",
38+
"topic":"/subscriptions/{subscription-id}/resourceGroups/RedisStressTests/providers/Microsoft.Cache/Redis/test-mcr",
39+
"data":{
40+
"name":"ScalingCompleted",
41+
"timestamp":"2020-12-09T21:50:19.9995668+00:00",
42+
"status":"Succeeded"},
43+
"subject":"ScalingCompleted",
44+
"dataversion":"1.0",
45+
"metadataVersion":"1",
46+
"eventTime":"2020-12-09T21:50:19.9995668+00:00"}]
47+
```
48+
49+
### Microsoft.Cache.ImportRDBCompleted event
50+
51+
```json
52+
[{
53+
"id":"9b87886d-21a5-4af5-8e3e-10c4b8dac73b",
54+
"eventType":"Microsoft.Cache.ImportRDBCompleted",
55+
"topic":"/subscriptions/{subscription-id}/resourceGroups/RedisStressTests/providers/Microsoft.Cache/Redis/test-mcr",
56+
"data":{
57+
"name":"ImportRDBCompleted",
58+
"timestamp":"2020-12-09T21:50:19.9995668+00:00",
59+
"status":"Succeeded"},
60+
"subject":"ImportRDBCompleted",
61+
"dataversion":"1.0",
62+
"metadataVersion":"1",
63+
"eventTime":"2020-12-09T21:50:19.9995668+00:00"}]
64+
```
65+
66+
### Microsoft.Cache.ExportRDBCompleted event
67+
68+
```json
69+
[{
70+
"id":"9b87886d-21a5-4af5-8e3e-10c4b8dac73b",
71+
"eventType":"Microsoft.Cache.ExportRDBCompleted",
72+
"topic":"/subscriptions/{subscription-id}/resourceGroups/RedisStressTests/providers/Microsoft.Cache/Redis/test-mcr",
73+
"data":{
74+
"name":"ExportRDBCompleted",
75+
"timestamp":"2020-12-09T21:50:19.9995668+00:00",
76+
"status":"Succeeded"},
77+
"subject":"ExportRDBCompleted",
78+
"dataversion":"1.0",
79+
"metadataVersion":"1",
80+
"eventTime":"2020-12-09T21:50:19.9995668+00:00"}]
81+
```
82+
83+
### Microsoft.Cache.ScalingCompleted
84+
85+
```json
86+
[{
87+
"id":"9b87886d-21a5-4af5-8e3e-10c4b8dac73b",
88+
"eventType":"Microsoft.Cache.ScalingCompleted",
89+
"topic":"/subscriptions/{subscription-id}/resourceGroups/RedisStressTests/providers/Microsoft.Cache/Redis/test-mcr",
90+
"data":{
91+
"name":"ScalingCompleted",
92+
"timestamp":"2020-12-09T21:50:19.9995668+00:00",
93+
"status":"Succeeded"},
94+
"subject":"ScalingCompleted",
95+
"dataversion":"1.0",
96+
"metadataVersion":"1",
97+
"eventTime":"2020-12-09T21:50:19.9995668+00:00"}]
98+
```
99+
100+
### Event properties
101+
102+
An event has the following top-level data:
103+
104+
| Property | Type | Description |
105+
| -------- | ---- | ----------- |
106+
| topic | string | Full resource path to the event source. This field is not writeable. Event Grid provides this value. |
107+
| subject | string | Publisher-defined path to the event subject. |
108+
| eventType | string | One of the registered event types for this event source. |
109+
| eventTime | string | The time the event is generated based on the provider's UTC time. |
110+
| id | string | Unique identifier for the event. |
111+
| data | object | Azure Cache for Redis event data. |
112+
| dataVersion | string | The schema version of the data object. The publisher defines the schema version. |
113+
| metadataVersion | string | The schema version of the event metadata. Event Grid defines the schema of the top-level properties. Event Grid provides this value. |
114+
115+
The data object has the following properties:
116+
117+
| Property | Type | Description |
118+
| -------- | ---- | ----------- |
119+
| timestamp | string | The time at which the event occurred. |
120+
| name | string | The name of the event. |
121+
| status | string | The status of the event. Failed or succeeded. |
122+
123+
124+
## Tutorials and how-tos
125+
126+
|Title |Description |
127+
|---------|---------|
128+
| [Quickstart: route Azure Cache for Redis events to a custom web endpoint with Azure CLI]() | Shows how to use Azure CLI to send Azure Cache for Redis events to a WebHook. |
129+
| [Azure Cache for Redis Event Grid Overview](../../azure-cache-for-redis/cache-event-grid.md) | Overview of integrating Azure Cache for Redis with Event Grid. |
130+
131+
## Next steps
132+
133+
* For an introduction to Azure Event Grid, see [What is Event Grid?](overview.md)
134+
* For more information about creating an Azure Event Grid subscription, see [Event Grid subscription schema](subscription-creation-schema.md).
135+

0 commit comments

Comments
 (0)
Please sign in to comment.