Event Grid に CloudEvents v1.0 スキーマを使用する

  • [アーティクル]

Azure Event Grid は、既定のイベント スキーマに加え、CloudEvents v1.0 および HTTP プロトコル バインディングの JSON 実装のイベントをネイティブでサポートします。 CloudEvents は、イベント データを記述するためのオープンな仕様です。

CloudEvents を使用すると、クラウド ベースのイベントを発行したり使用したりするための共通のイベント スキーマを提供し、相互運用性を簡略化することができます。 このスキーマを使用すれば、ツールを統一化したり、イベントのルーティングや処理方法を標準化したり、外部のイベント スキーマを共通の方法で逆シリアル化することができます。 共通のスキーマを使用することで、プラットフォーム間での作業をより簡単に統合できます。

CloudEvents は、Cloud Native Computing Foundation を通じ、複数のコラボレーター (マイクロソフトを含む) によって構築されています。 現在、バージョン 1.0 が提供されています。

この記事では、Event Grid で CloudEvents スキーマを使用する方法について説明します。

CloudEvent スキーマ

次に示すのは、CloudEvents 形式の Azure Blob Storage イベントの例です。

{
    "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 スキーマと Event Grid スキーマで配信されるイベントのヘッダー値は同じです (content-type を除く)。 CloudEvents スキーマの場合、そのヘッダー値は "content-type":"application/cloudevents+json; charset=utf-8" です。 Event Grid スキーマの場合、そのヘッダー値は "content-type":"application/json; charset=utf-8" です。

CloudEvents 用の構成

Event Grid は、CloudEvents スキーマ内のイベントの入力と出力の両方に使用できます。 次の表は、使用できる変換を示しています。

Event Grid リソース 入力スキーマ 配信スキーマ
システム トピック Event Grid スキーマ Event Grid スキーマまたは CloudEvents スキーマ
カスタム トピックまたはドメイン Event Grid スキーマ Event Grid スキーマまたは CloudEvents スキーマ
カスタム トピックまたはドメイン CloudEvents スキーマ CloudEvents スキーマ
カスタム トピックまたはドメイン カスタム スキーマ カスタム スキーマ、Event Grid スキーマ、または CloudEvents スキーマ
パートナー トピック CloudEvents スキーマ CloudEvents スキーマ

いずれのイベント スキーマについても、Event Grid では、Event Grid トピックへの発行時やイベント サブスクリプションの作成時に検証が必要です。

詳細については、「Event Grid security and authentication」(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 を使用したエンドポイントの検証

Event Grid を既に使い慣れている場合、不正使用を防ぐためのエンドポイント検証ハンドシェイクをご存じかもしれません。 CloudEvents v1.0 を使用すると、HTTP OPTIONS メソッドによって、独自の不正使用防止のセマンティクスが実装されます。 詳細については、イベント配信用の HTTP 1.1 Web Hooks (バージョン 1.0) を参照してください。 出力に CloudEvents スキーマを使用すると、Event Grid では、Event Grid の検証イベント メカニズムではなく 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 portal 開発エクスペリエンス

Azure portal を使用して 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 Event Grid トリガー」を参照してください。

次のステップ