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

项目
12/18/2024

Azure 事件网格本身支持 CloudEvents v1.0 的 JSON 实现和 HTTP 协议绑定中的事件。 CloudEvents 是一种用于描述事件数据的开放规范。 CloudEvents 提供的常用事件架构适合发布和使用基于云的事件，因此可简化互操作性。可以通过此架构使用统一的工具、以标准方式路由和处理事件，以及以通用方式反序列化外部事件架构。使用通用架构可以更轻松地跨平台集成工作。

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

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

使用 CloudEvents 架构的示例事件

下面是一个采用 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}",    
    "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 用于系统事件（例如 Blob 存储事件和 IoT 中心事件）和自定义事件。除了支持 CloudEvents 外，事件网格还支持专有的、不可扩展但功能齐全的事件网格事件格式。下表描述了将 CloudEvents 和事件网格格式用作主题中的输入架构和事件订阅中的输出架构时支持的转换。将 CloudEvents 用作输入架构时，无法使用事件网格输出架构，因为 CloudEvents 支持事件网格架构不支持的扩展属性。

输入架构	输出架构
CloudEvents 格式	CloudEvents 格式
事件网格格式	CloudEvents 格式
事件网格格式	事件网格格式

对于所有事件架构，事件网格都要求在发布到事件网格主题时以及在创建事件订阅时进行验证。有关详细信息，请参阅事件网格安全性和身份验证。

输入架构

创建自定义主题时，可以使用 input-schema 参数设置自定义主题的输入架构。

对于 Azure CLI，请使用：

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

对于 PowerShell，请使用：

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

输出架构

创建事件订阅时，可以使用 event-delivery-schema 参数设置输出架构。

对于 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

与 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 事件网格触发器。

通过