Azure 事件方格適用于 .NET 的用戶端程式庫 - 4.14.1 版

發行項
04/03/2023

Azure Event Grid 可讓您以事件型架構輕鬆地建立應用程式。 Event Grid 服務會針對任何應用程式，完全管理從任何來源到任何目的地的所有事件路由。 Azure 服務事件和自訂事件可以直接發佈至服務，然後即可篩選事件並傳送給各種收件者，例如內建處理常式或自訂 Webhook。若要深入瞭解Azure 事件方格：什麼是事件方格？

使用用戶端程式庫來Azure 事件方格：

使用事件方格事件、雲端事件 1.0 或自訂架構，將事件發佈至事件方格服務
取用已傳遞至事件處理常式的事件
產生 SAS 權杖，以驗證用戶端發佈事件至Azure 事件方格主題

| 原始程式碼套件 (NuGet) | API 參考檔 | 產品檔 | 樣品 | 移轉指南

開始使用

安裝套件

從 NuGet 安裝用戶端程式庫：

dotnet add package Azure.Messaging.EventGrid

必要條件

您必須擁有具有自訂事件方格主題或網域的 Azure 訂用帳戶和 Azure 資源群組。請遵循此逐步教學課程來註冊事件方格資源提供者，並使用Azure 入口網站建立事件方格主題。使用Azure CLI有類似的教學課程。

驗證用戶端

為了讓用戶端程式庫與主題或網域互動，您需要 endpoint 事件方格主題的和 credential ，其可以使用主題的存取金鑰來建立。

您可以在 Azure 入口網站或使用下列 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>"));

使用共用存取簽章進行驗證

事件方格也支援使用共用存取簽章進行驗證，其可讓您存取在特定時間到期的資源，而不需要共用您的存取金鑰。一般而言，工作流程會是一個應用程式會產生 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 事件方格提供與 Azure Active Directory (Azure AD) 的整合，以進行要求的身分識別型驗證。透過 Azure AD，您可以使用角色型存取控制 (RBAC) ，將Azure 事件方格資源的存取權授與使用者、群組或應用程式。 Azure 身分識別程式庫提供簡單的 Azure Active Directory 驗證支援。

若要使用 Azure Active Directory 將事件傳送至主題或網域，已驗證的身分識別應該已指派「EventGrid 資料傳送者」角色。

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

重要概念

如需一般事件方格概念的資訊：Azure 事件方格概念。

EventGridPublisherClient

發行者會將事件傳送至事件方格服務。 Microsoft 會發行數個 Azure 服務的事件。您可以使用從自己的應用程式 EventGridPublisherClient 發佈事件。

事件結構描述

事件是最少量的資訊，可完整描述系統中發生的情況。事件方格支援多個編碼事件的架構。建立自訂主題或網域時，您可以指定發行事件時將使用的架構。

事件格線結構描述

雖然您可以將主題設定為使用自訂架構，但使用已定義的事件方格架構比較常見。請參閱這裡的規格和需求。

CloudEvents v1.0 結構描述

另一個選項是使用 CloudEvents v1.0 架構。 CloudEvents 是 Cloud Native Computing Foundation 專案，可產生一個規格，以常見方式描述事件資料。您可以在這裡找到 CloudEvents 的服務摘要。

無論您的主題或網域設定為使用何種架構， EventGridPublisherClient 都會用來將事件發佈至該主題。 SendEvents使用或 SendEventsAsync 方法來發佈。

事件傳遞

依事件方格傳遞給取用者的事件會 以 JSON 的形式傳遞。視要傳遞至的取用者類型而定，事件方格服務可能會在單一承載中傳遞一或多個事件。處理事件會根據事件傳遞為的架構而有所不同。不過，一般模式會維持不變：

將事件從 JSON 剖析為個別事件。根據事件架構 (事件方格或 CloudEvents) ，您現在可以存取信封上事件的基本資訊， (屬性上存在的所有事件，例如事件時間和類型) 。
還原序列化事件資料。若為 EventGridEvent 或 CloudEvent ，使用者可以藉由還原序列化為特定類型，嘗試存取事件承載或資料。此時您可以提供自訂序列化程式，以正確解碼資料。

執行緒安全

我們保證所有用戶端實例方法都是安全線程，且彼此獨立 (指導方針) 。這可確保重複使用用戶端實例的建議一律是安全的，即使是跨執行緒也一樣。

其他概念

將事件方格事件發佈至事件方格主題

使用執行將事件發佈至事件方格 EventGridPublisherClient 。使用提供的 SendEvent/SendEventAsync 方法，將單一事件發佈至主題。

// 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 發佈至事件方格主題

使用執行將事件發佈至事件方格 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);

將事件方格事件發佈至事件方格網域

事件網域是與相同應用程式相關的大量事件方格主題管理工具。您可以將它視為可含有數千個個別主題的中繼主題。當您建立事件網域時，您會收到類似於您是否已在事件方格中建立主題的發行端點。

若要將事件發佈至事件網域中的任何主題，請將事件推送至網域的端點，與自訂主題的方式相同。唯一的差別是必須指定您想要將事件傳遞到其中的主題。

// 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 服務可作為事件處理常式。

注意：如果使用 Webhook 傳遞 事件方格架構，事件方格會要求您證明 Webhook 端點的擁有權，才能開始將事件傳遞至該端點。在事件訂閱建立時，事件方格會將訂用帳戶驗證事件傳送至您的端點，如下所示。在這裡深入瞭解如何完成交握： 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));

還原序列化事件資料

從這裡，您可以藉由在屬性上 Data 呼叫 ToObjectFromJson<T>() 來還原序列化至特定類型，以存取事件資料。為了還原序列化為正確的類型， EventType CloudEvents 的屬性 (Type) 有助於區分不同的事件。自訂事件資料應該使用泛型方法 ToObjectFromJson<T>() 還原序列化。另外還有一個擴充方法 ToObject<T>() 可接受自訂 ObjectSerializer 來還原序列化事件資料。

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。

請注意，如果您使用自訂事件種類搭配 EventType 值，稍後會由服務和 SDK 新增為系統事件，則的 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， JsonException 則會在呼叫 Parse 或 ParseMany 時擲回。
如果事件架構未對應至還原序列化的型別 (，例如 CloudEvent.Parse 呼叫 EventGridSchema 事件) ， ArgumentException 則會擲回。
如果在 Parse 包含多個事件的資料上呼叫， ArgumentException 則會擲回。 ParseMany 應該改用在這裡。

設定主控台記錄

如果您想要深入了解針對服務提出的要求，您也可以輕鬆地啟用主控台記錄。

分散式追蹤

事件方格程式庫支援現用散發追蹤。為了遵守 CloudEvents 規格的分散式追蹤指引，程式庫會在啟用分散式追蹤時，在的上 ExtensionAttributesCloudEvent 設定 traceparent 和 tracestate 。若要深入瞭解如何在應用程式中啟用分散式追蹤，請參閱 Azure SDK 分散式追蹤檔。

Kubernetes 上的事件方格

此程式庫已在 Kubernetes 上使用 Azure Arc 進行測試和驗證。

下一步

如需事件方格用戶端程式庫的常見用法，請參閱這裡： https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.14.1/sdk/eventgrid/Azure.Messaging.EventGrid/samples 事件方格範例。

參與

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資訊，請造訪 https://cla.microsoft.com.

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。請遵循 bot 提供的指示。您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

曝光數

共用方式為

Azure 事件方格適用于 .NET 的用戶端程式庫 - 4.14.1 版

開始使用

安裝套件

必要條件

驗證用戶端

使用主題存取金鑰進行驗證

使用共用存取簽章進行驗證

使用 Azure Active Directory 進行驗證

重要概念

EventGridPublisherClient

事件結構描述

事件格線結構描述

CloudEvents v1.0 結構描述

事件傳遞

執行緒安全

其他概念

範例

將事件方格事件發佈至事件方格主題

將 CloudEvents 發佈至事件方格主題

將事件方格事件發佈至事件方格網域

接收和還原序列化事件

還原序列化事件資料

疑難排解

服務回應

還原序列化事件資料

設定主控台記錄

分散式追蹤

Kubernetes 上的事件方格

下一步

參與

意見反應

其他資源