Azure 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 スキーマの使用について説明します。
CloudEvents スキーマを使用したサンプル イベント
次に示すのは、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}",
"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 スキーマ内のイベントの入力と出力の両方に使用できます。 CloudEvents は、システム イベント (Blob Storage イベントや IoT Hub イベントなど) とカスタム イベントに使用できます。 Event Grid では、CloudEvents のサポートに加えて、拡張不能だが完全に機能する独自の Event Grid イベント形式がサポートされています。 次の表では、CloudEvents と Event Grid の形式をトピックの入力スキーマとして、およびイベント サブスクリプションの出力スキーマとして使用する場合にサポートされる変換について説明します。 CloudEvents は Event Grid スキーマではサポートされていない拡張属性をサポートしているため、入力スキーマとして CloudEvents を使用する場合は、Event Grid 出力スキーマを使用できません。
| 入力スキーマ | 出力スキーマ |
|---|---|
| CloudEvents 形式 | CloudEvents 形式 |
| Event Grid 形式 | CloudEvents 形式 |
| Event Grid 形式 | Event Grid 形式 |
いずれのイベント スキーマについても、Event Grid では、Event Grid トピックへの発行時やイベント サブスクリプションの作成時に検証が必要です。 詳細については、「Event Grid security and authentication」(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 portal 開発エクスペリエンス
Azure portal を使用して 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 を使用したエンドポイントの検証について詳しくは、「CloudEvents 1.0 を使用したエンドポイントの検証」をご覧ください。