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

[アーティクル]
10/18/2023

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 トピックに発行する

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 宛てに質問またはコメントをお送りください。

インプレッション数

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

作業の開始

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

前提条件

クライアントを認証する

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

Shared Access Signature を使用した認証

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

主要な概念

EventGridPublisherClient

イベントスキーマ

Event Grid スキーマ

CloudEvents v1.0 スキーマ

イベント配信

スレッドセーフ

その他の概念

例

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

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

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

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

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

トラブルシューティング

サービス応答

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

コンソールログの設定

分散トレース

Kubernetes 上の Event Grid

次の手順

共同作成

フィードバック

フィードバック

その他のリソース

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

作業の開始

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

前提条件

クライアントを認証する

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

Shared Access Signature を使用した認証

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

主要な概念

EventGridPublisherClient

イベント スキーマ

Event Grid スキーマ

CloudEvents v1.0 スキーマ

イベント配信

スレッド セーフ

その他の概念

例

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

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

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

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

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

トラブルシューティング

サービス応答

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

コンソール ログの設定

分散トレース

Kubernetes 上の Event Grid

次の手順

共同作成

フィードバック

フィードバック

その他のリソース

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

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

イベントスキーマ

スレッドセーフ

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

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

コンソールログの設定