.NET 用Azure Event Grid クライアント ライブラリ - バージョン 4.20.0

Azure Event Grid では、イベント ベースのアーキテクチャを備えたアプリケーションを簡単に作成することができます。 Event Grid サービスは、任意のアプリケーションの任意のソースから任意の宛先へのイベントのすべてのルーティングを完全に管理します。 Azure サービス イベントとカスタム イベントはサービスに直接発行できます。このイベントをフィルター処理して、組み込みのハンドラーやカスタム Webhook など、さまざまな受信者に送信できます。 Azure Event Gridの詳細については、「Event Grid とは」を参照してください。

クライアント ライブラリを使用して、次のAzure Event Gridを行います。

• Event Grid イベント、Cloud Event 1.0、またはカスタム スキーマを使用して Event Grid サービスにイベントを発行する

• イベント ハンドラーに配信されたイベントを使用する

• Azure Event Grid トピックにクライアント発行イベントを認証するための SAS トークンを生成する

  ソースコード | パッケージ (NuGet) | API リファレンス ドキュメント | 製品ドキュメント | サンプル | 移行ガイド

作業の開始

パッケージをインストールする

NuGet からクライアント ライブラリをインストールします:

dotnet add package Azure.Messaging.EventGrid

前提条件

カスタム Event Grid トピックまたはドメインを持つ Azure サブスクリプション と Azure リソース グループが必要です。 この詳細なチュートリアルに従って、Event Grid リソース プロバイダーを登録し、Azure portalを使用して Event Grid トピックを作成します。 Azure CLI を使用した同様のチュートリアルがあります。

クライアントを認証する

クライアント ライブラリがトピックまたはドメインと対話するには、Event Grid トピックの と、トピックのアクセス キーをcredential使用して作成できる が必要endpointです。

Event Grid トピックのエンドポイントは、 Azure Portal または以下の Azure CLI スニペットを使用して確認できます。

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

アクセス キーは、 ポータルから、または次の Azure CLI スニペットを使用して見つけることもできます。

az eventgrid topic key list --name <your-resource-name> --resource-group <your-resource-group-name> --query "key1"

トピック アクセス キーを使用した認証

アクセス キーとトピック エンドポイントを取得したら、次のようにパブリッシャー クライアントを作成できます。

EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri("<endpoint>"),
    new AzureKeyCredential("<access-key>"));

Shared Access Signature を使用した認証

Event Grid では、共有アクセス署名を使用した認証もサポートされています。これにより、アクセス キーを共有することなく、特定の時間までに期限切れになるリソースへのアクセスを提供できます。 一般に、ワークフローは、あるアプリケーションが SAS 文字列を生成し、文字列を使用する別のアプリケーションに文字列を渡すということです。 SAS を生成します。

var builder = new EventGridSasBuilder(new Uri(topicEndpoint), DateTimeOffset.Now.AddHours(1));
var keyCredential = new AzureKeyCredential(topicAccessKey);
string sasToken = builder.GenerateSas(keyCredential);

コンシューマーの観点から使用する方法を次に示します。

var sasCredential = new AzureSasCredential(sasToken);
EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri(topicEndpoint),
    sasCredential);

EventGridPublisherClient では、 を使用した EventGridPublisherClientOptions一連の構成オプションも受け入れられます。 たとえば、イベント データを JSON にシリアル化するために使用するカスタム シリアライザーを指定できます。

Azure Active Directory を使用して認証する

Azure Event Gridでは、要求の ID ベースの認証のために Azure Active Directory (Azure AD) との統合が提供されます。 Azure AD では、ロールベースのアクセス制御 (RBAC) を使用して、Azure Event Grid リソースへのアクセス権をユーザー、グループ、またはアプリケーションに付与できます。 Azure Identity ライブラリは、認証に対する Azure Active Directory のサポートを簡単に提供します。

Azure Active Directory を使用してトピックまたはドメインにイベントを送信するには、認証された ID に "EventGrid データ送信者" ロールが割り当てられている必要があります。

EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri(topicEndpoint),
    new DefaultAzureCredential());

主要な概念

Event Grid の一般的な概念の詳細については、「Azure Event Gridの概念」を参照してください。

EventGridPublisherClient

パブリッシャーは Event Grid サービスにイベントを送信します。 Microsoft では、いくつかの Azure サービスのためのイベントを発行しています。 を使用して、独自のアプリケーションからイベントを EventGridPublisherClient発行できます。

イベント スキーマ

イベントは、システムで発生した何かを完全に説明する最小量の情報です。 Event Grid では、イベントをエンコードするための複数のスキーマがサポートされています。 カスタム トピックまたはドメインを作成するときは、イベントの発行時に使用するスキーマを指定します。

Event Grid スキーマ

カスタム スキーマを使用するようにトピックを構成することもできますが、既に定義されている Event Grid スキーマを使用する方が一般的です。 仕様と要件については、 こちらを参照してください。

CloudEvents v1.0 スキーマ

もう 1 つのオプションは、CloudEvents v1.0 スキーマを使用することです。 CloudEvents は、一般的な方法でイベント データを記述するための仕様を生成する Cloud Native Computing Foundation プロジェクトです。 CloudEvents のサービスの概要については、 こちらを参照してください。

トピックまたはドメインが使用するように構成されているスキーマに関係なく、 EventGridPublisherClient イベントを発行するために使用されます。 発行には または SendEventsSendEventsAsync メソッドを使用します。

イベント配信

Event Grid によってコンシューマーに配信されるイベントは 、JSON として配信されます。 配信されるコンシューマーの種類によっては、Event Grid サービスが 1 つのペイロードの一部として 1 つ以上のイベントを配信する場合があります。 イベントの処理は、イベントが配信されたスキーマによって異なります。 ただし、一般的なパターンは変わりません。

• JSON から個々のイベントにイベントを解析します。 イベント スキーマ (Event Grid または CloudEvents) に基づいて、エンベロープ上のイベントに関する基本情報 (イベントの時刻や種類など、すべてのイベントに存在するプロパティ) にアクセスできるようになりました。
• イベント データを逆シリアル化します。 または CloudEventをEventGridEvent指定すると、ユーザーは特定の型に逆シリアル化することで、イベント ペイロード (データ) へのアクセスを試みることができます。 この時点でカスタム シリアライザーを指定して、データを正しくデコードできます。

スレッド セーフ

すべてのクライアント インスタンス メソッドがスレッド セーフであり、相互に独立していることを保証します (ガイドライン)。 これにより、クライアント インスタンスの再利用に関する推奨事項は、スレッド間でも常に安全になります。

その他の概念

クライアント オプション | 応答 | へのアクセス実行時間の長い操作 | エラーの | 処理診断 | あざける | クライアントの有効期間

例

• Event Grid イベントを Event Grid トピックに発行する
• CloudEvents を Event Grid トピックに発行する
• Event Grid イベントを Event Grid ドメインに発行する
• イベントの受信と逆シリアル化

Event Grid イベントを Event Grid トピックに発行する

Event Grid へのイベントの発行は、 を使用して実行されます EventGridPublisherClient。 指定 SendEvent/SendEventAsync されたメソッドを使用して、1 つのイベントをトピックに発行します。

// Add EventGridEvents to a list to publish to the topic
EventGridEvent egEvent =
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        "This is the event data");

// Send the event
await client.SendEventAsync(egEvent);

イベントのバッチを発行するには、 メソッドを使用します SendEvents/SendEventsAsync 。

// Example of a custom ObjectSerializer used to serialize the event payload to JSON
var myCustomDataSerializer = new JsonObjectSerializer(
    new JsonSerializerOptions()
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase
    });

// Add EventGridEvents to a list to publish to the topic
List<EventGridEvent> eventsList = new List<EventGridEvent>
{
    // EventGridEvent with custom model serialized to JSON
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        new CustomModel() { A = 5, B = true }),

    // EventGridEvent with custom model serialized to JSON using a custom serializer
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        myCustomDataSerializer.Serialize(new CustomModel() { A = 5, B = true })),
};

// Send the events
await client.SendEventsAsync(eventsList);

CloudEvents を Event Grid トピックに発行する

Event Grid へのイベントの発行は、 を使用して実行されます EventGridPublisherClient。 指定 SendEvents/SendEventsAsync したメソッドを使用して、トピックにイベントを発行します。

// Example of a custom ObjectSerializer used to serialize the event payload to JSON
var myCustomDataSerializer = new JsonObjectSerializer(
    new JsonSerializerOptions()
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase
    });

// Add CloudEvents to a list to publish to the topic
List<CloudEvent> eventsList = new List<CloudEvent>
{
    // CloudEvent with custom model serialized to JSON
    new CloudEvent(
        "/cloudevents/example/source",
        "Example.EventType",
        new CustomModel() { A = 5, B = true }),

    // CloudEvent with custom model serialized to JSON using a custom serializer
    new CloudEvent(
        "/cloudevents/example/source",
        "Example.EventType",
        myCustomDataSerializer.Serialize(new CustomModel() { A = 5, B = true }),
        "application/json"),

    // CloudEvents also supports sending binary-valued data
    new CloudEvent(
        "/cloudevents/example/binarydata",
        "Example.EventType",
        new BinaryData(Encoding.UTF8.GetBytes("This is treated as binary data")),
        "application/octet-stream")};

// Send the events
await client.SendEventsAsync(eventsList);

Event Grid イベントを Event Grid ドメインに発行する

イベント ドメインは、同じアプリケーションに関連する多数の Event Grid トピックの管理ツールです。 数千の個々のトピックを含めることができるメタ トピックと考えることができます。 イベント ドメインを作成するときに、Event Grid でトピックを作成した場合と同じような発行エンドポイントが与えられます。

イベント ドメイン内の任意のトピックにイベントを発行するには、カスタム トピックの場合と同じ方法でイベントをドメインのエンドポイントにプッシュします。 唯一の違いは、イベントの配信先となるトピックを指定する必要があることです。

// Add EventGridEvents to a list to publish to the domain
// Don't forget to specify the topic you want the event to be delivered to!
List<EventGridEvent> eventsList = new List<EventGridEvent>
{
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        "This is the event data")
    {
        Topic = "MyTopic"
    }
};

// Send the events
await client.SendEventsAsync(eventsList);

CloudEvents を送信する場合は、CloudEvent ソースがドメイン トピックとして使用されます。

List<CloudEvent> eventsList = new List<CloudEvent>();

for (int i = 0; i < 10; i++)
{
    CloudEvent cloudEvent = new CloudEvent(
        // the source is mapped to the domain topic
        $"Subject-{i}",
        "Microsoft.MockPublisher.TestEvent",
        "hello")
    {
        Id = $"event-{i}",
        Time = DateTimeOffset.Now
    };
    eventsList.Add(cloudEvent);
}

await client.SendEventsAsync(eventsList);

イベントの受信と逆シリアル化

イベント ハンドラーとして機能するいくつかの異なる Azure サービスがあります。

注: Event Grid スキーマのイベント配信に Webhook を使用する場合、Event Grid では、そのエンドポイントへのイベントの配信を開始する前に、Webhook エンドポイントの所有権を証明する必要があります。 イベント サブスクリプションの作成時に、Event Grid は次のようにサブスクリプション検証イベントをエンドポイントに送信します。 ハンドシェイクの完了の詳細については、 Webhook イベント配信に関するページを参照してください。 CloudEvents スキーマの場合、サービスは HTTP オプション メソッドを使用して接続を検証します。 詳細については、 CloudEvents の検証に関するページを参照してください。

イベントがイベント ハンドラーに配信されたら、JSON ペイロードをイベントの一覧に逆シリアル化できます。

EventGridEventの使用

// Parse the JSON payload into a list of events
EventGridEvent[] egEvents = EventGridEvent.ParseMany(BinaryData.FromStream(httpContent));

CloudEventの使用

var bytes = await httpContent.ReadAsByteArrayAsync();
// Parse the JSON payload into a list of events
CloudEvent[] cloudEvents = CloudEvent.ParseMany(new BinaryData(bytes));

イベント データの逆シリアル化

ここから、 プロパティで を呼び出 ToObjectFromJson<T>() して特定の型に逆シリアル化することで、イベント データに Data アクセスできます。 正しい型に逆シリアル化するために、 EventType プロパティ (Type CloudEvents の場合) は、異なるイベントを区別するのに役立ちます。 カスタム イベント データは、ジェネリック メソッド ToObjectFromJson<T>()を使用して逆シリアル化する必要があります。 イベント データを逆シリアル化するためのカスタムObjectSerializerを受け入れる拡張メソッドToObject<T>()もあります。

foreach (CloudEvent cloudEvent in cloudEvents)
{
    switch (cloudEvent.Type)
    {
        case "Contoso.Items.ItemReceived":
            // By default, ToObjectFromJson<T> uses System.Text.Json to deserialize the payload
            ContosoItemReceivedEventData itemReceived = cloudEvent.Data.ToObjectFromJson<ContosoItemReceivedEventData>();
            Console.WriteLine(itemReceived.ItemSku);
            break;
        case "MyApp.Models.CustomEventType":
            // One can also specify a custom ObjectSerializer as needed to deserialize the payload correctly
            TestPayload testPayload = cloudEvent.Data.ToObject<TestPayload>(myCustomSerializer);
            Console.WriteLine(testPayload.Name);
            break;
        case SystemEventNames.StorageBlobDeleted:
            // Example for deserializing system events using ToObjectFromJson<T>
            StorageBlobDeletedEventData blobDeleted = cloudEvent.Data.ToObjectFromJson<StorageBlobDeletedEventData>();
            Console.WriteLine(blobDeleted.BlobType);
            break;
    }
}

TryGetSystemEventData()の使用

ほとんどのシステム イベントを想定している場合は、スイッチを入 TryGetSystemEventData() れ、パターン マッチングを使用して個々のイベントに対して処理を行う方がクリーンな場合があります。 イベントがシステム イベントでない場合、メソッドは false を返し、out パラメーターは null になります。

注意として、後でサービスと SDK によってシステム イベントとして追加される EventType 値を持つカスタム イベントの種類を使用している場合、 の TryGetSystemEventData 戻り値は から false に true変更されます。 これは、サービスによって既に送信されているが SDK にまだ追加されていないイベントに対して独自のカスタム イベントを事前に作成している場合に発生する可能性があります。 この場合は、 プロパティでDataジェネリック ToObjectFromJson<T> メソッドを使用して、アップグレード後にコード フローが自動的に変更されないようにすることをお勧めします (もちろん、カスタム モデルではなく、新しくリリースされたシステム イベント モデルを使用するようにコードを変更することもできます)。

foreach (EventGridEvent egEvent in egEvents)
{
    // If the event is a system event, TryGetSystemEventData will return the deserialized system event
    if (egEvent.TryGetSystemEventData(out object systemEvent))
    {
        switch (systemEvent)
        {
            case SubscriptionValidationEventData subscriptionValidated:
                Console.WriteLine(subscriptionValidated.ValidationCode);
                break;
            case StorageBlobCreatedEventData blobCreated:
                Console.WriteLine(blobCreated.BlobType);
                break;
            // Handle any other system event type
            default:
                Console.WriteLine(egEvent.EventType);
                // we can get the raw Json for the event using Data
                Console.WriteLine(egEvent.Data.ToString());
                break;
        }
    }
    else
    {
        switch (egEvent.EventType)
        {
            case "MyApp.Models.CustomEventType":
                TestPayload deserializedEventData = egEvent.Data.ToObjectFromJson<TestPayload>();
                Console.WriteLine(deserializedEventData.Name);
                break;
            // Handle any other custom event type
            default:
                Console.Write(egEvent.EventType);
                Console.WriteLine(egEvent.Data.ToString());
                break;
        }
    }
}

トラブルシューティング

サービス応答

SendEvents() は、サービスから HTTP 応答コードを返します。 RequestFailedExceptionは、失敗した要求に対するサービス応答としてスローされます。 例外には、サービスから返された応答コードに関する情報が含まれています。

イベント データの逆シリアル化

• イベント データが有効な JSON でない場合は、 または ParseManyを呼び出Parseすときに がJsonExceptionスローされます。
• イベント スキーマが、逆シリアル化される型 (EventGridSchema イベントでの 呼び出し CloudEvent.Parse など) ArgumentException に対応していない場合は、 がスローされます。
• Parseが複数のイベントを含むデータで 呼び出されると、 ArgumentException がスローされます。 ParseMany は、代わりにここで使用する必要があります。

コンソール ログの設定

また、サービスに対して行う要求の詳細を確認する場合は、コンソールのログ記録を簡単に有効にすることもできます。

分散トレース

Event Grid ライブラリでは、すぐに使えるトレースの配布がサポートされています。 CloudEvents の仕様の分散トレースのガイダンスに準拠するため、このライブラリでは、分散トレースを有効にするときに CloudEvent の ExtensionAttributes に traceparent と tracestate を設定します。 アプリケーションで分散トレースを有効にする方法の詳細については、Azure SDK の分散トレースに関するドキュメントを参照してください。

Kubernetes 上の Event Grid

このライブラリは、Azure Arc を使用して Kubernetes でテストおよび検証されています。

次の手順

https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.20.0/sdk/eventgrid/Azure.Messaging.EventGrid/samples Event Grid クライアント ライブラリの一般的な使用方法については、Event Grid サンプルに関するページを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、「 共同作成者使用許諾契約書」を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。