搭配使用 CloudEvents v1.0 結構描述與事件方格

發行項
04/16/2024

除了預設事件結構描述以外，Azure 事件方格在本質上也支援 CloudEvents v1.0 的 JSON 實作和 HTTP 通訊協定繫結中的事件。 CloudEvents 是用來說明事件資料的開放式規格。

CloudEvents 提供用以發佈和取用雲端型事件的常見事件結構描述，可簡化互通性。此結構描述可支援統一的工具、路由和處理事件的標準方式，以及將外部事件結構描述還原序列化的通用方式。您可以利用通用結構描述更輕鬆地整合跨平台的工作。

目前有數個共同作業者 (包括 Microsoft) 正透過 Cloud Native Computing Foundation 建置 CloudEvents。目前可用的版本為 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.windows.net/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 結構描述

對於所有的事件結構描述，事件方格在發佈至事件方格主題和建立事件訂閱時，都需要進行驗證。

如需詳細資訊，請參閱 Event Grid 安全性和驗證。

輸入結構描述

當您建立自訂主題時，您可以設定自訂主題的輸入結構描述。

對於 Azure CLI，請使用：

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

對於 PowerShell，請使用：

New-AzEventGridTopic -ResourceGroupName gridResourceGroup -Location westcentralus -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 事件方格觸發程序。

下一步

如需關於監視事件傳遞的資訊，請參閱監視 Event Grid 訊息傳遞。
建議您測試、評論和參與 CloudEvents。
若要了解 Event Grid 訂用帳戶的建立，請參閱 Event Grid 訂用帳戶結構描述。

共用方式為