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

Azure 事件方格在本質上也支援 CloudEvents v1.0 的 JSON 實作和 HTTP 通訊協定繫結中的事件。 CloudEvents 是用來說明事件資料的開放式規格。 CloudEvents 會提供可發佈及使用雲端型事件的通用事件結構描述來簡化互通性。 此結構描述可支援統一的工具、路由和處理事件的標準方式，以及將外部事件結構描述還原序列化的通用方式。 您可以利用通用結構描述更輕鬆地整合跨平台的工作。

目前有數個共同作業者 (包括 Microsoft) 正透過 Cloud Native Computing Foundation 建置 CloudEvents。 目前可用的版本為 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.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，例如 Blob 儲存體事件和 IoT 中樞事件以及自訂事件。 除了支援 CloudEvents 之外，事件方格還支援專屬、不可擴充且功能完整的事件方格事件格式。 下表描述當使用 CloudEvents 和事件方格格式做為主題中的輸入結構描述，以及作為事件訂用帳戶中的輸出結構描述時所支援的轉換。 使用 CloudEvents 做為輸入結構描述時，無法使用事件方格輸出結構描述，因為 CloudEvents 支援事件方格結構描述不支援的延伸模組屬性。

輸入結構描述	輸出結構描述
CloudEvents 格式	CloudEvents 格式
事件方格格式	CloudEvents 格式
事件方格格式	事件方格格式

對於所有的事件結構描述，事件方格在發佈至事件方格主題和建立事件訂用帳戶時，都需要進行驗證。 如需詳細資訊，請參閱 Event Grid 安全性和驗證。

輸入結構描述

當您建立自訂主題時，您可以使用 input-schema 參數來設定自訂主題的輸入結構描述。

對於 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

輸出結構描述

當您使用 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 函式，請遵循下列步驟：

1. 將 function.json 檔案中的參數名稱更新為 cloudEvent。

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

2. 如下列範例程式碼所示更新 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 1.0 進行端點驗證。