将 CloudEvents v1.0 架构与事件网格配合使用

项目
02/29/2024

除了采用默认事件架构的事件，Azure 事件网格本身还支持采用 CloudEvents v1.0 的 JSON 实现和 HTTP 协议绑定的事件。 CloudEvents 是一种用于描述事件数据的开放规范。

CloudEvents 提供的常用事件架构适合发布和使用基于云的事件，因此可简化互操作性。可以通过此架构使用统一的工具、以标准方式路由和处理事件，以及以通用方式反序列化外部事件架构。使用通用架构可以更轻松地跨平台集成工作。

CloudEvents 是由包括 Microsoft 在内的多个协作者通过 Cloud Native Computing Foundation 构建的。它目前的发布版本为 1.0。

本文介绍如何将 CloudEvents 架构与事件网格配合使用。

CloudEvent 架构

下面是一个采用 CloudEvents 格式的 Azure Blob 存储事件示例：

{
    "specversion": "1.0",
    "type": "Microsoft.Storage.BlobCreated",  
    "source": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Storage/storageAccounts/{storage-account}",
    "id": "9aeb0fdf-c01e-0131-0922-9eb54906e209",
    "time": "2019-11-18T15:13:39.4589254Z",
    "subject": "blobServices/default/containers/{storage-container}/blobs/{new-file}",
    "dataschema": "#",
    "data": {
        "api": "PutBlockList",
        "clientRequestId": "4c5dd7fb-2c48-4a27-bb30-5361b5de920a",
        "requestId": "9aeb0fdf-c01e-0131-0922-9eb549000000",
        "eTag": "0x8D76C39E4407333",
        "contentType": "image/png",
        "contentLength": 30699,
        "blobType": "BlockBlob",
        "url": "https://gridtesting.blob.core.chinacloudapi.cn/testcontainer/{new-file}",
        "sequencer": "000000000000000000000000000099240000000000c41c18",
        "storageDiagnostics": {
            "batchId": "681fe319-3006-00a8-0022-9e7cde000000"
        }
    }
}

有关可用字段及其类型和定义的详细说明，请参阅 CloudEvents v1.0。

在 CloudEvents 架构和事件网格架构中传递的事件的标头值是相同的，但 content-type 除外。对于 CloudEvents 架构，该标头值为 "content-type":"application/cloudevents+json; charset=utf-8"。对于事件网格架构，该标头值为 "content-type":"application/json; charset=utf-8"。

配置 CloudEvents

可以将事件网格用于 CloudEvents 架构中的事件的输入和输出。下表说明了可能的转换：

事件网格资源	输入架构	传递架构
系统主题	事件网格架构	事件网格架构或 CloudEvents 架构
自定义主题/域	事件网格架构	事件网格架构或 CloudEvents 架构
自定义主题/域	CloudEvents 架构	CloudEvents 架构
自定义主题/域	自定义架构	自定义架构、事件网格架构或 CloudEvents 架构
合作伙伴主题	CloudEvents 架构	CloudEvents 架构

对于所有事件架构，事件网格都要求在发布到事件网格主题时以及在创建事件订阅时进行验证。

有关详细信息，请参阅事件网格安全性和身份验证。

输入架构

在创建自定义主题时为自定义主题设置输入架构。

对于 Azure CLI，请使用：

az eventgrid topic create --name demotopic -l chinaeast -g gridResourceGroup --input-schema cloudeventschemav1_0

对于 PowerShell，请使用：

New-AzEventGridTopic -ResourceGroupName gridResourceGroup -Location chinaeast -Name demotopic -InputSchema CloudEventSchemaV1_0

输出架构

在创建事件订阅时设置输出架构。

对于 Azure CLI，请使用：

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

az eventgrid event-subscription create --name demotopicsub --source-resource-id $topicID --endpoint <endpoint_URL> --event-delivery-schema cloudeventschemav1_0

对于 PowerShell，请使用：

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

New-AzEventGridSubscription -ResourceId $topicid -EventSubscriptionName <event_subscription_name> -Endpoint <endpoint_URL> -DeliverySchema CloudEventSchemaV1_0

使用 CloudEvents v1.0 验证终结点

如果熟悉事件网格，你可能会了解用于防止滥用的终结点验证握手。 CloudEvents v1.0 使用 HTTP OPTIONS 方法来实现自己的滥用防护语义。若要了解有关详细信息，请参阅适用于事件传递的 HTTP 1.1 Webhook - 版本 1.0。使用 CloudEvents 架构进行输出时，事件网格将使用 CloudEvents v1.0 滥用防护取代事件网格验证事件机制。

与 Azure Functions 配合使用

Visual Studio 或 Visual Studio Code

如果使用 Visual Studio 或 Visual Studio Code 以及 C# 编程语言来开发函数，请确保使用的是最新的 Microsoft.Azure.WebJobs.Extensions.EventGrid NuGet 包（3.3.1 或更高版本）。

在 Visual Studio 中，使用“工具”->“NuGet 包管理器”->“包管理器控制台”，然后运行 Install-Package 命令 (Install-Package Microsoft.Azure.WebJobs.Extensions.EventGrid -Version 3.3.1)。或者，右键单击“解决方案资源管理器”窗口中的项目，选择“管理 NuGet 包”菜单以浏览 NuGet 包，然后进行安装或将它更新到最新版本。

在 VS Code 中，更新 Azure Functions 项目的 csproj 文件中 Microsoft.Azure.WebJobs.Extensions.EventGrid 包的版本号。

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.EventGrid" Version="3.3.1" />
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.1.1" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

以下示例演示了在 Visual Studio 或 Visual Studio Code 中开发的 Azure Functions 版本 3.x 函数。它使用 CloudEvent 绑定参数和 EventGridTrigger。

using Azure.Messaging;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class CloudEventTriggerFunction
    {
        [FunctionName("CloudEventTriggerFunction")]
        public static void Run(ILogger logger, [EventGridTrigger] CloudEvent e)
        {
            logger.LogInformation("Event received {type} {subject}", e.Type, e.Subject);
        }
    }
}

Azure 门户开发体验

如果使用 Azure 门户开发 Azure 函数，请执行以下步骤：

将 function.json 文件中参数的名称更新为 cloudEvent。

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "cloudEvent",
      "direction": "in"
    }
  ]
}

按以下示例代码所示更新 run.csx 文件。

#r "Azure.Core"

using Azure.Messaging;

public static void Run(CloudEvent cloudEvent, ILogger logger)
{
    logger.LogInformation("Event received {type} {subject}", cloudEvent.Type, cloudEvent.Subject);
}

注意

有关详细信息，请参阅适用于 Azure Functions 的 Azure 事件网格触发器。

后续步骤

有关监视事件传送的信息，请参阅监视事件网格消息传送。
我们鼓励你测试、评论并参与编写 CloudEvents。
有关创建 Azure 事件网格订阅的详细信息，请参阅事件网格订阅架构。

通过