使用事件域管理主题和发布事件Manage topics and publish events using event domains

本文介绍以下操作:This article shows how to:

  • 创建事件网格域Create an Event Grid domain
  • 订阅事件网格主题Subscribe to event grid topics
  • 列出密钥List keys
  • 将事件发布到域Publish events to a domain

若要了解事件域,请参阅了解用于管理事件网格主题的事件域To learn about event domains, see Understand event domains for managing Event Grid topics.

重要

使用 PowerShell 的 Azure 功能必须已安装 AzureRM 模块。Using this Azure feature from PowerShell requires the AzureRM module installed. 该模块是旧模块,仅适用于 Windows PowerShell 5.1,它不再接收新功能。This is an older module only available for Windows PowerShell 5.1 that no longer receives new features. 针对相同版本的 PowerShell 进行安装时,AzAzureRM 模块不兼容。The Az and AzureRM modules are not compatible when installed for the same versions of PowerShell. 如果需要两个版本,请执行以下操作:If you need both versions:

  1. 在 PowerShell 5.1 会话中卸载 Az 模块Uninstall the Az module from a PowerShell 5.1 session.
  2. 在 PowerShell 5.1 会话中安装 AzureRM 模块Install the AzureRM module from a PowerShell 5.1 session.
  3. 下载并安装 PowerShell Core 6.x 或更高版本Download and install PowerShell Core 6.x or later.
  4. 在 PowerShell Core 会话中安装 Az 模块Install the Az module in a PowerShell Core session.

安装预览功能Install preview feature

此功能为预览版。This feature is in preview. 若要使用它,必须安装预览扩展或模块。To use it, you must install a preview extension or module.

安装适用于 Azure CLI 的扩展Install extension for Azure CLI

对于 Azure CLI,需要事件网格扩展For Azure CLI, you need the Event Grid extension.

对于本地安装:For a local installation:

  1. 在本地卸载 Azure CLI。Uninstall Azure CLI locally.
  2. 安装最新版本的 Azure CLI。Install the latest version of Azure CLI.
  3. 启动命令窗口。Launch command window.
  4. 卸载早期版本的扩展 az extension remove -n eventgridUninstall previous versions of the extension az extension remove -n eventgrid
  5. 安装扩展 az extension add -n eventgridInstall the extension az extension add -n eventgrid

安装适用于 PowerShell 的模块Install module for PowerShell

对于 PowerShell,需要 AzureRM.EventGrid 模块For PowerShell, you need the AzureRM.EventGrid module.

对于本地安装:For a local installation:

  1. 以管理员身份打开 PowerShell 控制台Open PowerShell console as administrator
  2. 安装模块 Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGalleryInstall the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

如果 -AllowPrerelease 参数不可用,请使用以下步骤:If the -AllowPrerelease parameter isn't available, use the following steps:

  1. 运行 Install-Module PowerShellGet -ForceRun Install-Module PowerShellGet -Force
  2. 运行 Update-Module PowerShellGetRun Update-Module PowerShellGet
  3. 关闭 PowerShell 控制台Close the PowerShell console
  4. 以管理员身份重启 PowerShellRestart PowerShell as administrator
  5. 安装模块 Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGalleryInstall the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

创建事件域Create an Event Domain

若要管理大型主题集,请创建一个事件域。To manage large sets of topics, create an event domain.

# If you haven't already installed the extension, do it now.
# This extension is required for preview features.
az extension add --name eventgrid

az eventgrid domain create \
  -g <my-resource-group> \
  --name <my-domain-name> \
  -l <location>

创建成功后会返回以下值:Successful creation returns the following values:

{
  "endpoint": "https://<my-domain-name>.chinanorth2-1.eventgrid.azure.cn/api/events",
  "id": "/subscriptions/<sub-id>/resourceGroups/<my-resource-group>/providers/Microsoft.EventGrid/domains/<my-domain-name>",
  "inputSchema": "EventGridSchema",
  "inputSchemaMapping": null,
  "location": "chinaeast",
  "name": "<my-domain-name>",
  "provisioningState": "Succeeded",
  "resourceGroup": "<my-resource-group>",
  "tags": null,
  "type": "Microsoft.EventGrid/domains"
}

请记下 endpointid,因为需要使用它们来管理域和发布事件。Note the endpoint and id as they're required to manage the domain and publish events.

管理对主题的访问Manage access to topics

可通过角色分配来管理对主题的访问。Managing access to topics is done via role assignment. 角色分配使用基于角色的访问控制来限制对 Azure 资源的操作,仅允许经授权用户在特定范围内执行操作。Role assignment uses role-based access control to limit operations on Azure resources to authorized users at a certain scope.

事件网格包含两个内置角色,可以使用这些角色为特定用户分配对域中不同主题的访问权限。Event Grid has two built-in roles, which you can use to assign particular users access on various topics within a domain. 这些角色为 EventGrid EventSubscription Contributor (Preview)EventGrid EventSubscription Reader (Preview),分别用于创建/删除订阅,以及只允许列出事件订阅。These roles are EventGrid EventSubscription Contributor (Preview), which allows for creation and deletion of subscriptions, and EventGrid EventSubscription Reader (Preview), which only allows for listing of event subscriptions.

以下 Azure CLI 命令将 alice@contoso.com 限制为只能在主题 demotopic1 上创建或删除事件订阅:The following Azure CLI command limits alice@contoso.com to creating and deleting event subscriptions only on topic demotopic1:

az role assignment create \
  --assignee alice@contoso.com \
  --role "EventGrid EventSubscription Contributor (Preview)" \
  --scope /subscriptions/<sub-id>/resourceGroups/<my-resource-group>/providers/Microsoft.EventGrid/domains/<my-domain-name>/topics/demotopic1

有关管理对事件网格操作的访问权限的详细信息,请参阅事件网格安全性和身份验证For more information about managing access for Event Grid operations, see Event Grid security and authentication.

创建主题和订阅Create topics and subscriptions

事件网格服务根据创建域主题事件订阅的调用,在域中自动创建和管理相应的主题。The Event Grid service automatically creates and manages the corresponding topic in a domain based on the call to create an event subscription for a domain topic. 没有单独的步骤可在域中创建主题。There's no separate step to create a topic in a domain. 同样,删除某个主题的最后一个事件订阅时,也会删除该主题。Similarly, when the last event subscription for a topic is deleted, the topic is deleted as well.

订阅域中主题的过程与订阅其他任何 Azure 资源相同。Subscribing to a topic in a domain is the same as subscribing to any other Azure resource. 对于源资源 ID,指定之前在创建域时返回的事件域 ID。For the source resource ID, specify the event domain ID returned when creating the domain earlier. 若要指定想要订阅的主题,请将 /topics/<my-topic> 添加到源资源 ID 的末尾。To specify the topic you want to subscribe to, add /topics/<my-topic> to the end of the source resource ID. 若要创建接收域中的所有事件的域范围事件订阅,请指定事件域 ID 且不要指定任何主题。To create a domain scope event subscription that receives all events in the domain, specify the event domain ID without specifying any topics.

通常情况下,将由你在前面的部分中向其授予了访问权限的用户创建订阅。Typically, the user you granted access to in the preceding section would create the subscription. 为了简化本文,将由你创建订阅。To simplify this article, you create the subscription.

az eventgrid event-subscription create \
  --name <event-subscription> \
  --source-resource-id "/subscriptions/<sub-id>/resourceGroups/<my-resource-group>/providers/Microsoft.EventGrid/domains/<my-domain-name>/topics/demotopic1" \
  --endpoint https://contoso.chinacloudsites.cn/api/updates

如果需要将事件订阅到某个测试终结点,始终可以部署能够显示传入事件的预生成 Web 应用If you need a test endpoint to subscribe your events to, you can always deploy a pre-built web app that displays the incoming events. 可将事件发送到测试网站 (https://<your-site-name>.chinacloudsites.cn/api/updates)。You can send your events to your test website at https://<your-site-name>.chinacloudsites.cn/api/updates.

Button to Deploy to Aquent.

为主题设置的权限存储在 Azure Active Directory 中,必须显式删除。Permissions that are set for a topic are stored in Azure Active Directory and must be deleted explicitly. 如果用户对主题拥有写访问权限,则删除事件订阅不会撤消用户创建事件订阅的权限。Deleting an event subscription won't revoke a users access to create event subscriptions if they have write access on a topic.

将事件发布到事件网格域Publish events to an Event Grid Domain

将事件发布到域的过程与发布到自定义主题相同。Publishing events to a domain is the same as publishing to a custom topic. 但是,不是发布到自定义主题,而是将所有事件发布到域终结点。However, instead of publishing to the custom topic, you publish all events to the domain endpoint. 在 JSON 事件数据中,可以指定要将事件发送到的主题。In the JSON event data, you specify the topic you wish the events to go to. 例如,以下事件数组会导致将包含 "id": "1111" 的事件发送到主题 demotopic1,将包含 "id": "2222" 的事件发送到主题 demotopic2The following array of events would result in event with "id": "1111" to topic demotopic1 while event with "id": "2222" would be sent to topic demotopic2:

[{
  "topic": "demotopic1",
  "id": "1111",
  "eventType": "maintenanceRequested",
  "subject": "myapp/vehicles/diggers",
  "eventTime": "2018-10-30T21:03:07+00:00",
  "data": {
    "make": "Contoso",
    "model": "Small Digger"
  },
  "dataVersion": "1.0"
},
{
  "topic": "demotopic2",
  "id": "2222",
  "eventType": "maintenanceCompleted",
  "subject": "myapp/vehicles/tractors",
  "eventTime": "2018-10-30T21:04:12+00:00",
  "data": {
    "make": "Contoso",
    "model": "Big Tractor"
  },
  "dataVersion": "1.0"
}]

若要使用 Azure CLI 获取域终结点,请使用:To get the domain endpoint with Azure CLI, use

az eventgrid domain show \
  -g <my-resource-group> \
  -n <my-domain>

若要获取域的密钥,请使用:To get the keys for a domain, use:

az eventgrid domain key list \
  -g <my-resource-group> \
  -n <my-domain>

然后,使用偏好的方法发出 HTTP POST,将事件发布到事件网格域。And then use your favorite method of making an HTTP POST to publish your events to your Event Grid domain.

后续步骤Next steps