Azure Event Grid .NET SDK

Azure.Messaging.EventGrid (.NET)

Azure Event Grid のトピック、ドメイン、名前空間にイベントを発行するためのクライアントライブラリ。

インストール

# トピックおよびドメイン向け（プッシュ配信）
dotnet add package Azure.Messaging.EventGrid

# 名前空間向け（プル配信）
dotnet add package Azure.Messaging.EventGrid.Namespaces

# CloudNative CloudEvents の相互運用のため
dotnet add package Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents

現在のバージョン: 4.28.0（安定版）

環境変数

EVENT_GRID_TOPIC_ENDPOINT=https://<topic-name>.<region>.eventgrid.azure.net/api/events  # 必須: Event Grid トピックまたはドメインのエンドポイント
EVENT_GRID_TOPIC_KEY=<access-key>  # AzureKeyCredential 認証の場合のみ必須
EVENT_GRID_NAMESPACE_ENDPOINT=https://<namespace>.<region>.eventgrid.azure.net  # オプション: Event Grid 名前空間エンドポイント
EVENT_GRID_TOPIC_NAME=<topic-name>  # 必須: Event Grid トピック名
EVENT_GRID_SUBSCRIPTION_NAME=<subscription-name>  # オプション: Event Grid サブスクリプション名
AZURE_TOKEN_CREDENTIALS=prod  # 本番環境で DefaultAzureCredential を使用する場合のみ必須

クライアント階層

プッシュ配信（トピック/ドメイン）
└── EventGridPublisherClient
    ├── SendEventAsync(EventGridEvent)
    ├── SendEventsAsync(IEnumerable<EventGridEvent>)
    ├── SendEventAsync(CloudEvent)
    └── SendEventsAsync(IEnumerable<CloudEvent>)

プル配信（名前空間）
├── EventGridSenderClient
│   └── SendAsync(CloudEvent)
└── EventGridReceiverClient
    ├── ReceiveAsync()
    ├── AcknowledgeAsync()
    ├── ReleaseAsync()
    └── RejectAsync()

認証

API キー認証

using Azure;
using Azure.Messaging.EventGrid;

EventGridPublisherClient client = new(
    new Uri("https://mytopic.eastus-1.eventgrid.azure.net/api/events"),
    new AzureKeyCredential("<access-key>"));

Microsoft Entra トークン資格情報

using Azure.Identity;
using Azure.Messaging.EventGrid;

// ローカル開発: DefaultAzureCredential。本番環境: AZURE_TOKEN_CREDENTIALS=prod または AZURE_TOKEN_CREDENTIALS=<specific_credential> を設定
var credential = new DefaultAzureCredential(
    DefaultAzureCredential.DefaultEnvironmentVariableName
);
// または本番環境では特定の資格情報を直接使用:
// 参照: https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes
// var credential = new ManagedIdentityCredential();
EventGridPublisherClient client = new(
    new Uri("https://mytopic.eastus-1.eventgrid.azure.net/api/events"),
    credential);

SAS トークン認証

string sasToken = EventGridPublisherClient.BuildSharedAccessSignature(
    new Uri(topicEndpoint),
    DateTimeOffset.UtcNow.AddHours(1),
    new AzureKeyCredential(topicKey));

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

イベントの発行

EventGridEvent スキーマ

EventGridPublisherClient client = new(
    new Uri(topicEndpoint),
    new AzureKeyCredential(topicKey));

// 単一イベント
EventGridEvent egEvent = new(
    subject: "orders/12345",
    eventType: "Order.Created",
    dataVersion: "1.0",
    data: new { OrderId = "12345", Amount = 99.99 });

await client.SendEventAsync(egEvent);

// イベントのバッチ
List<EventGridEvent> events = new()
{
    new EventGridEvent(
        subject: "orders/12345",
        eventType: "Order.Created",
        dataVersion: "1.0",
        data: new OrderData { OrderId = "12345", Amount = 99.99 }),
    new EventGridEvent(
        subject: "orders/12346",
        eventType: "Order.Created",
        dataVersion: "1.0",
        data: new OrderData { OrderId = "12346", Amount = 149.99 })
};

await client.SendEventsAsync(events);

CloudEvent スキーマ

CloudEvent cloudEvent = new(
    source: "/orders/system",
    type: "Order.Created",
    data: new { OrderId = "12345", Amount = 99.99 });

cloudEvent.Subject = "orders/12345";
cloudEvent.Id = Guid.NewGuid().ToString();
cloudEvent.Time = DateTimeOffset.UtcNow;

await client.SendEventAsync(cloudEvent);

// CloudEvents のバッチ
List<CloudEvent> cloudEvents = new()
{
    new CloudEvent("/orders", "Order.Created", new { OrderId = "1" }),
    new CloudEvent("/orders", "Order.Updated", new { OrderId = "2" })
};

await client.SendEventsAsync(cloudEvents);

Event Grid ドメインへの発行

// イベントはドメインルーティングのために Topic プロパティを指定する必要があります
List<EventGridEvent> events = new()
{
    new EventGridEvent(
        subject: "orders/12345",
        eventType: "Order.Created",
        dataVersion: "1.0",
        data: new { OrderId = "12345" })
    {
        Topic = "orders-topic"  // ドメイントピック名
    },
    new EventGridEvent(
        subject: "inventory/item-1",
        eventType: "Inventory.Updated",
        dataVersion: "1.0",
        data: new { ItemId = "item-1" })
    {
        Topic = "inventory-topic"
    }
};

await client.SendEventsAsync(events);

カスタムシリアル化

using System.Text.Json;

var serializerOptions = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

var customSerializer = new JsonObjectSerializer(serializerOptions);

EventGridEvent egEvent = new(
    subject: "orders/12345",
    eventType: "Order.Created",
    dataVersion: "1.0",
    data: customSerializer.Serialize(new OrderData { OrderId = "12345" }));

await client.SendEventAsync(egEvent);

プル配信（名前空間）

名前空間トピックへのイベント送信

using Azure;
using Azure.Messaging;
using Azure.Messaging.EventGrid.Namespaces;

var senderClient = new EventGridSenderClient(
    new Uri(namespaceEndpoint),
    topicName,
    new AzureKeyCredential(topicKey));

// 単一イベントの送信
CloudEvent cloudEvent = new("employee_source", "Employee.Created", 
    new { Name = "John", Age = 30 });
await senderClient.SendAsync(cloudEvent);

// バッチ送信
await senderClient.SendAsync(new[]
{
    new CloudEvent("source", "type", new { Name = "Alice" }),
    new CloudEvent("source", "type", new { Name = "Bob" })
});

イベントの受信と処理

var receiverClient = new EventGridReceiverClient(
    new Uri(namespaceEndpoint),
    topicName,
    subscriptionName,
    new AzureKeyCredential(topicKey));

// イベントの受信
ReceiveResult result = await receiverClient.ReceiveAsync(maxEvents: 10);

List<string> lockTokensToAck = new();
List<string> lockTokensToRelease = new();

foreach (ReceiveDetails detail in result.Details)
{
    CloudEvent cloudEvent = detail.Event;
    string lockToken = detail.BrokerProperties.LockToken;
    
    try
    {
        // イベントの処理
        Console.WriteLine($"イベント: {cloudEvent.Type}, データ: {cloudEvent.Data}");
        lockTokensToAck.Add(lockToken);
    }
    catch (Exception)
    {
        // 再試行のために解放
        lockTokensToRelease.Add(lockToken);
    }
}

// 正常に処理されたイベントを確認
if (lockTokensToAck.Any())
{
    await receiverClient.AcknowledgeAsync(lockTokensToAck);
}

// 再試行のためにイベントを解放
if (lockTokensToRelease.Any())
{
    await receiverClient.ReleaseAsync(lockTokensToRelease);
}

イベントの拒否（デッドレター）

// 処理できないイベントを拒否
await receiverClient.RejectAsync(new[] { lockToken });

イベントの消費（Azure Functions）

EventGridEvent トリガー

using Azure.Messaging.EventGrid;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;

public static class EventGridFunction
{
    [FunctionName("ProcessEventGridEvent")]
    public static void Run(
        [EventGridTrigger] EventGridEvent eventGridEvent,
        ILogger log)
    {
        log.LogInformation($"イベントタイプ: {eventGridEvent.EventType}");
        log.LogInformation($"サブジェクト: {eventGridEvent.Subject}");
        log.LogInformation($"データ: {eventGridEvent.Data}");
    }
}

CloudEvent トリガー

using Azure.Messaging;
using Microsoft.Azure.Functions.Worker;

public class CloudEventFunction
{
    [Function("ProcessCloudEvent")]
    public void Run(
        [EventGridTrigger] CloudEvent cloudEvent,
        FunctionContext context)
    {
        var logger = context.GetLogger("ProcessCloudEvent");
        logger.LogInformation($"イベントタイプ: {cloudEvent.Type}");
        logger.LogInformation($"ソース: {cloudEvent.Source}");
        logger.LogInformation($"データ: {cloudEvent.Data}");
    }
}

イベントの解析

EventGridEvent の解析

// JSON 文字列から
string json = "..."; // Event Grid webhook ペイロード
EventGridEvent[] events = EventGridEvent.ParseMany(BinaryData.FromString(json));

foreach (EventGridEvent egEvent in events)
{
    if (egEvent.TryGetSystemEventData(out object systemEvent))
    {
        // システムイベントの処理
        switch (systemEvent)
        {
            case StorageBlobCreatedEventData blobCreated:
                Console.WriteLine($"Blob が作成されました: {blobCreated.Url}");
                break;
        }
    }
    else
    {
        // カスタムイベントの処理
        var customData = egEvent.Data.ToObjectFromJson<MyCustomData>();
    }
}

CloudEvent の解析

CloudEvent[] cloudEvents = CloudEvent.ParseMany(BinaryData.FromString(json));

foreach (CloudEvent cloudEvent in cloudEvents)
{
    var data = cloudEvent.Data.ToObjectFromJson<MyEventData>();
    Console.WriteLine($"タイプ: {cloudEvent.Type}, データ: {data}");
}

システムイベント

// 一般的なシステムイベントタイプ
using Azure.Messaging.EventGrid.SystemEvents;

// ストレージイベント
StorageBlobCreatedEventData blobCreated;
StorageBlobDeletedEventData blobDeleted;

// リソースイベント
ResourceWriteSuccessEventData resourceCreated;
ResourceDeleteSuccessEventData resourceDeleted;

// App Service イベント
WebAppUpdatedEventData webAppUpdated;

// Container Registry イベント
ContainerRegistryImagePushedEventData imagePushed;

// IoT Hub イベント
IotHubDeviceCreatedEventData deviceCreated;

主要な型のリファレンス

型	目的
EventGridPublisherClient	トピック/ドメインへの発行
EventGridSenderClient	名前空間トピックへの送信
EventGridReceiverClient	名前空間サブスクリプションからの受信
EventGridEvent	Event Grid ネイティブスキーマ
CloudEvent	CloudEvents 1.0 スキーマ
ReceiveResult	プル配信の応答
ReceiveDetails	ブローカープロパティを持つイベント
BrokerProperties	ロックトークン、配信カウント

イベントスキーマの比較

機能	EventGridEvent	CloudEvent
標準	Azure 固有	CNCF 標準
必須フィールド	subject, eventType, dataVersion, data	source, type
拡張性	制限あり	拡張属性
相互運用性	Azure のみ	クロスプラットフォーム

ベストプラクティス

1. CloudEvents を使用する — 新しい実装では CloudEvents を推奨（業界標準）
2. イベントをバッチ処理する — 効率化のために複数イベントを1回の呼び出しで送信
3. Entra ID を使用する — アクセスキーよりもマネージド ID を優先
4. べき等ハンドラー — イベントは複数回配信される可能性がある
5. イベント TTL を設定する — 名前空間イベントの有効期限を構成
6. 部分的な障害を処理する — イベントを個別に確認/解放
7. デッドレターを使用する — 失敗したイベントのためにデッドレターを設定
8. スキーマを検証する — 処理前にイベントデータを検証

エラーハンドリング

using Azure;

try
{
    await client.SendEventAsync(cloudEvent);
}
catch (RequestFailedException ex) when (ex.Status == 401)
{
    Console.WriteLine("認証に失敗しました - 資格情報を確認してください");
}
catch (RequestFailedException ex) when (ex.Status == 403)
{
    Console.WriteLine("認可に失敗しました - RBAC 権限を確認してください");
}
catch (RequestFailedException ex) when (ex.Status == 413)
{
    Console.WriteLine("ペイロードが大きすぎます - イベントあたり最大 1MB、バッチ合計 1MB");
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Event Grid エラー: {ex.Status} - {ex.Message}");
}

フェイルオーバーパターン

try
{
    var primaryClient = new EventGridPublisherClient(primaryUri, primaryKey);
    await primaryClient.SendEventsAsync(events);
}
catch (RequestFailedException)
{
    // セカンダリリージョンにフェイルオーバー
    var secondaryClient = new EventGridPublisherClient(secondaryUri, secondaryKey);
    await secondaryClient.SendEventsAsync(events);
}

関連 SDK

SDK	目的	インストール
Azure.Messaging.EventGrid	トピック/ドメイン（この SDK）	dotnet add package Azure.Messaging.EventGrid
Azure.Messaging.EventGrid.Namespaces	プル配信	dotnet add package Azure.Messaging.EventGrid.Namespaces
Azure.Identity	認証	dotnet add package Azure.Identity
Microsoft.Azure.WebJobs.Extensions.EventGrid	Azure Functions トリガー	dotnet add package Microsoft.Azure.WebJobs.Extensions.EventGrid

参考リンク

リソース	URL
NuGet パッケージ	https://www.nuget.org/packages/Azure.Messaging.EventGrid
API リファレンス	https://learn.microsoft.com/dotnet/api/azure.messaging.eventgrid
クイックスタート	https://learn.microsoft.com/azure/event-grid/custom-event-quickstart
プル配信	https://learn.microsoft.com/azure/event-grid/pull-delivery-overview
GitHub ソース	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/eventgrid/Azure.Messaging.EventGrid