您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

将 CloudEvents 架构与事件网格配合使用Use CloudEvents schema with Event Grid

除了采用默认事件架构的事件,Azure 事件网格本身还支持采用 CloudEvents JSON 架构的事件。In addition to its default event schema, Azure Event Grid natively supports events in the CloudEvents JSON schema. CloudEvents 是一种用于描述事件数据的开放规范CloudEvents is an open specification for describing event data.

CloudEvents 提供的常用事件架构适合发布和使用基于云的事件,因此可简化互操作性。CloudEvents simplifies interoperability by providing a common event schema for publishing, and consuming cloud based events. 可以通过此架构使用统一的工具、以标准方式路由和处理事件,以及以通用方式反序列化外部事件架构。This schema allows for uniform tooling, standard ways of routing & handling events, and universal ways of deserializing the outer event schema. 使用通用架构可以更轻松地跨平台集成工作。With a common schema, you can more easily integrate work across platforms.

CloudEvents 是由包括 Microsoft 在内的多个协作者通过 Cloud Native Computing Foundation 构建的。CloudEvents is being built by several collaborators, including Microsoft, through the Cloud Native Computing Foundation. 它目前的发布版本为 0.1。It's currently available as version 0.1.

本文介绍如何将 CloudEvents 架构与事件网格配合使用。This article describes how to use the CloudEvents schema with Event Grid.

重要

使用 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.

CloudShell 中:In CloudShell:

  • 如果之前已安装此扩展,请使用 az extension update -n eventgrid 进行更新If you've installed the extension previously, update it az extension update -n eventgrid
  • 如果之前尚未安装此扩展,请使用 az extension add -n eventgrid 安装If you haven't installed the extension previously, install it az extension add -n eventgrid

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

  1. 安装 Azure CLIInstall the Azure CLI. 请确保通过检查与具有最新版本, az --versionMake sure that you have the latest version, by checking with az --version.
  2. 卸载早期版本的扩展 az extension remove -n eventgridUninstall previous versions of the extension az extension remove -n eventgrid
  3. 安装eventgrid扩展名 az extension add -n eventgridInstall the eventgrid extension with az extension add -n eventgrid

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

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

CloudShell 中:In CloudShell:

  • 安装模块 Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGalleryInstall the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

对于本地安装: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

CloudEvent 架构CloudEvent schema

下面以示例方式说明了 CloudEvents 格式的 Azure Blob 存储事件:Here is an example of an Azure Blob Storage event in CloudEvents format:

{
    "cloudEventsVersion" : "0.1",
    "eventType" : "Microsoft.Storage.BlobCreated",
    "eventTypeVersion" : "",
    "source" : "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Storage/storageAccounts/{storage-account}#blobServices/default/containers/{storage-container}/blobs/{new-file}",
    "eventID" : "173d9985-401e-0075-2497-de268c06ff25",
    "eventTime" : "2018-04-28T02:18:47.1281675Z",
    "data" : {
      "api": "PutBlockList",
      "clientRequestId": "6d79dbfb-0e37-4fc4-981f-442c9ca65760",
      "requestId": "831e1650-001e-001b-66ab-eeb76e000000",
      "eTag": "0x8D4BCC2E4835CD0",
      "contentType": "application/octet-stream",
      "contentLength": 524288,
      "blobType": "BlockBlob",
      "url": "https://oc2d2817345i60006.blob.core.windows.net/oc2d2817345i200097container/oc2d2817345i20002296blob",
      "sequencer": "00000000000004420000000000028963",
      "storageDiagnostics": {
        "batchId": "b68529f3-68cd-4744-baa4-3c0498ec19f0"
      }
    }
}

CloudEvents v0.1 提供以下属性:CloudEvents v0.1 has the following properties available:

CloudEventsCloudEvents TypeType 示例 JSON 值Example JSON Value 描述Description 事件网格映射Event Grid Mapping
eventTypeeventType StringString "com.example.someevent""com.example.someevent" 发生的事件的类型Type of occurrence that happened eventTypeeventType
eventTypeVersioneventTypeVersion StringString "1.0""1.0" eventType 的版本(可选)The version of the eventType (Optional) dataVersiondataVersion
cloudEventsVersioncloudEventsVersion StringString "0.1""0.1" 事件使用的 CloudEvents 规范的版本The version of the CloudEvents specification the event uses 已传递passed through
sourcesource URIURI "/mycontext""/mycontext" 描述事件生成者Describes the event producer topic#subjecttopic#subject
eventIDeventID StringString "1234-1234-1234""1234-1234-1234" 事件的 IDID of the event idid
eventTimeeventTime TimestampTimestamp "2018-04-05T17:31:00Z""2018-04-05T17:31:00Z" 事件发生时的时间戳(可选)Timestamp of when the event happened (Optional) eventTimeeventTime
schemaURLschemaURL URIURI "https://myschema.com""https://myschema.com" 数据属性所遵循的架构的链接(可选)A link to the schema that the data attribute adheres to (Optional) 未使用not used
contentTypecontentType StringString "application/json""application/json" 描述数据编码格式(可选)Describe the data encoding format (Optional) 未使用not used
扩展extensions 映射Map { "extA": "vA", "extB", "vB" }{ "extA": "vA", "extB", "vB" } 任何其他的元数据(可选)Any additional metadata (Optional) 未使用not used
datadata ObjectObject { "objA": "vA", "objB", "vB" }{ "objA": "vA", "objB", "vB" } 事件有效负载(可选)The event payload (Optional) datadata

有关详细信息,请参阅 CloudEvents 规范For more information, see the CloudEvents spec.

在 CloudEvents 架构和事件网格架构中传递的事件的标头值是相同的,但 content-type 除外。The headers values for events delivered in the CloudEvents schema and the Event Grid schema are the same except for content-type. 对于 CloudEvents 架构,该标头值为 "content-type":"application/cloudevents+json; charset=utf-8"For CloudEvents schema, that header value is "content-type":"application/cloudevents+json; charset=utf-8". 对于事件网格架构,该标头值为 "content-type":"application/json; charset=utf-8"For Event Grid schema, that header value is "content-type":"application/json; charset=utf-8".

为 CloudEvents 配置事件网格Configure Event Grid for CloudEvents

可以将事件网格用于 CloudEvents 架构的事件的输入和输出。You can use Event Grid for both input and output of events in CloudEvents schema. 可以将 CloudEvents 用于系统事件(例如 Blob 存储事件和 IoT 中心事件)和自定义事件。You can use CloudEvents for system events, like Blob Storage events and IoT Hub events, and custom events. 它还可以将网络上的这些事件来回转换。It can also transform those events on the wire back and forth.

输入架构Input schema 输出架构Output schema
CloudEvents 格式CloudEvents format CloudEvents 格式CloudEvents format
事件网格格式Event Grid format CloudEvents 格式CloudEvents format
CloudEvents 格式CloudEvents format 事件网格格式Event Grid format
事件网格格式Event Grid format 事件网格格式Event Grid format

对于所有事件架构,事件网格都要求在发布到事件网格主题时以及在创建事件订阅时进行验证。For all event schemas, Event Grid requires validation when publishing to an event grid topic and when creating an event subscription. 有关详细信息,请参阅事件网格安全性和身份验证For more information, see Event Grid security and authentication.

输入架构Input schema

在创建自定义主题时为自定义主题设置输入架构。You set the input schema for a custom topic when you create the custom topic.

对于 Azure CLI,请使用:For Azure CLI, use:

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

az eventgrid topic create \
  --name <topic_name> \
  -l westcentralus \
  -g gridResourceGroup \
  --input-schema cloudeventv01schema

对于 PowerShell,请使用:For PowerShell, use:

# If you have not already installed the module, do it now.
# This module is required for preview features.
Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

New-AzureRmEventGridTopic `
  -ResourceGroupName gridResourceGroup `
  -Location westcentralus `
  -Name <topic_name> `
  -InputSchema CloudEventV01Schema

CloudEvents 的当前版本不支持对事件进行批处理。The current version of CloudEvents doesn't support batching of events. 若要使用 CloudEvent 架构将事件发布到某个主题,请单独发布每个事件。To publish events with CloudEvent schema to a topic, publish each event individually.

输出架构Output schema

在创建事件订阅时设置输出架构。You set the output schema when you create the event subscription.

对于 Azure CLI,请使用:For Azure CLI, use:

topicID=$(az eventgrid topic show --name <topic-name> -g gridResourceGroup --query id --output tsv)

az eventgrid event-subscription create \
  --name <event_subscription_name> \
  --source-resource-id $topicID \
  --endpoint <endpoint_URL> \
  --event-delivery-schema cloudeventv01schema

对于 PowerShell,请使用:For PowerShell, use:

$topicid = (Get-AzureRmEventGridTopic -ResourceGroupName gridResourceGroup -Name <topic-name>).Id

New-AzureRmEventGridSubscription `
  -ResourceId $topicid `
  -EventSubscriptionName <event_subscription_name> `
  -Endpoint <endpoint_URL> `
  -DeliverySchema CloudEventV01Schema

CloudEvents 的当前版本不支持对事件进行批处理。The current version of the CloudEvents doesn't support batching of events. 针对 CloudEvent 架构配置的事件订阅会单独接收每个事件。An event subscription that's configured for CloudEvent schema receives each event individually. 目前,在以 CloudEvents 架构传递事件时,无法为 Azure Functions 应用使用事件网格触发器。Currently, you can't use an Event Grid trigger for an Azure Functions app when the event is delivered in the CloudEvents schema. 使用 HTTP 触发器。Use an HTTP trigger. 有关实现在 CloudEvents 架构中接收事件的 HTTP 触发器的示例,请参阅使用 HTTP 触发器作为事件网格触发器For examples of implementing an HTTP trigger that receives events in the CloudEvents schema, see Use an HTTP trigger as an Event Grid trigger.

后续步骤Next steps