.NET için Azure Event Grid istemci kitaplığı - sürüm 4.14.1

  • Makale

Azure Event Grid, olay temelli mimarilerle kolayca uygulamalar derlemenize olanak tanır. Event Grid hizmeti, herhangi bir uygulama için herhangi bir kaynaktan herhangi bir hedefe tüm olayların yönlendirilmesi işlemini tam olarak yönetir. Azure hizmet olayları ve özel olaylar doğrudan hizmete yayımlanabilir ve burada olaylar filtrelenebilir ve yerleşik işleyiciler veya özel web kancaları gibi çeşitli alıcılara gönderilebilir. Azure Event Grid hakkında daha fazla bilgi edinmek için: Event Grid nedir?

Azure Event Grid için istemci kitaplığını kullanın:

Başlarken

Paketi yükleme

NuGet'ten istemci kitaplığını yükleyin:

dotnet add package Azure.Messaging.EventGrid

Önkoşullar

Özel Event Grid konusuna veya etki alanına sahip bir Azure aboneliğiniz ve Azure kaynak grubunuz olmalıdır. Event Grid kaynak sağlayıcısını kaydetmek ve Azure portal kullanarak Event Grid konuları oluşturmak için bu adım adım öğreticiyi izleyin. Azure CLI'nınkullanıldığı benzer bir öğretici vardır.

İstemcinin Kimliğini Doğrulama

İstemci kitaplığının bir konu veya etki alanıyla etkileşim kurabilmesi için, Event Grid konusunun ve konunun erişim anahtarı kullanılarak oluşturulabilen bir credentialöğesinin olması gerekirendpoint.

Event Grid konunuzun uç noktasını Azure Portal'da veya aşağıdaki Azure CLI parçacığını kullanarak bulabilirsiniz.

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

Erişim anahtarı portal aracılığıyla veya aşağıdaki Azure CLI kod parçacığı kullanılarak da bulunabilir:

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

Konu Erişim Anahtarı kullanarak kimlik doğrulaması yapma

Erişim anahtarınızı ve konu uç noktanızı aldıktan sonra yayımcı istemcisini aşağıdaki gibi oluşturabilirsiniz:

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

Paylaşılan Erişim İmzası kullanarak kimlik doğrulaması

Event Grid, erişim anahtarınızı paylaşmadan süresi belirli bir süre dolan bir kaynağa erişim sağlamaya olanak tanıyan paylaşılan erişim imzası ile kimlik doğrulamayı da destekler. Genellikle iş akışı, bir uygulamanın SAS dizesini oluşturması ve dizeyi dizeyi kullanacak başka bir uygulamaya devretmesi olabilir. SAS'yi oluşturma:

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

Tüketici açısından şu şekilde kullanılabilir:

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

EventGridPublisherClient ayrıca aracılığıyla EventGridPublisherClientOptionsbir dizi yapılandırma seçeneğini kabul eder. Örneğin, olay verilerini JSON'a seri hale getirmek için kullanılacak özel bir seri hale getirici belirtebilirsiniz.

Azure Active Directory'yi kullanarak kimlik doğrulama

Azure Event Grid, isteklerin kimlik tabanlı kimlik doğrulaması için Azure Active Directory (Azure AD) ile tümleştirme sağlar. Azure AD ile kullanıcılara, gruplara veya uygulamalara Azure Event Grid kaynaklarınıza erişim vermek için rol tabanlı erişim denetimini (RBAC) kullanabilirsiniz. Azure Kimlik kitaplığı, kimlik doğrulaması için kolay Azure Active Directory desteği sağlar.

Azure Active Directory kullanarak bir konuya veya etki alanına olay göndermek için, kimliği doğrulanmış kimliğin atanmış "EventGrid Veri Göndereni" rolüne sahip olması gerekir.

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

Önemli kavramlar

Genel Event Grid kavramları hakkında bilgi için: Azure Event Grid kavramları.

EventGridPublisherClient

Yayımcı olayları Event Grid hizmetine gönderir. Microsoft, çeşitli Azure hizmetleri için olaylar yayımlar. kullanarak EventGridPublisherClientkendi uygulamanızdan olayları yayımlayabilirsiniz.

Olay şemaları

Olay, sistemde gerçekleşen bir şeyi tam olarak açıklayan en küçük bilgi miktarıdır. Event Grid, olayları kodlamak için birden çok şemayı destekler. Özel bir konu veya etki alanı oluşturulduğunda, olayları yayımlarken kullanılacak şemayı belirtirsiniz.

Olay Kılavuz şeması

Konunuzu özel bir şema kullanacak şekilde yapılandırabilirsiniz ancak önceden tanımlanmış Event Grid şemasını kullanmak daha yaygındır. Belirtimlere ve gereksinimlere buradan bakın.

CloudEvents v1.0 şeması

Bir diğer seçenek de CloudEvents v1.0 şemasını kullanmaktır. CloudEvents , olay verilerini ortak bir şekilde tanımlamak için belirtim oluşturan bir Cloud Native Computing Foundation projesidir. CloudEvents'in hizmet özetini burada bulabilirsiniz.

Konunuzun veya etki alanınızın hangi şemayı kullanacak şekilde yapılandırıldığına bakılmaksızın, EventGridPublisherClient olay yayımlamak için kullanılır. Yayımlamak SendEvents için veya SendEventsAsync yöntemini kullanın.

Olay teslimi

Event Grid tarafından tüketicilere teslim edilen olaylar JSON olarak teslim edilir. Teslim edilen tüketicinin türüne bağlı olarak, Event Grid hizmeti tek bir yükün parçası olarak bir veya daha fazla olay teslim edebilir. Olayların işlenmesi, olayın hangi şema olarak teslim edildiğine göre farklı olacaktır. Ancak genel desen aynı kalır:

  • Olayları JSON'dan ayrı ayrı olaylara ayrıştırma. Olay şemasına (Event Grid veya CloudEvents) bağlı olarak artık zarfta olayla ilgili temel bilgilere erişebilirsiniz (olay zamanı ve türü gibi tüm olaylar için mevcut olan özellikler).
  • Olay verilerini seri durumdan çıkarma. EventGridEvent veya CloudEventdeğeri verüldüğünde, kullanıcı belirli bir türe seri durumdan çıkararak olay yüküne veya verilerine erişmeyi deneyebilir. Verilerin kodunu doğru şekilde çözmek için bu noktada özel bir seri hale getirici sağlayabilirsiniz.

İş parçacığı güvenliği

Tüm istemci örneği yöntemlerinin iş parçacığı açısından güvenli ve birbirinden bağımsız olduğunu garanti ediyoruz (kılavuz). Bu, istemci örneklerini yeniden kullanma önerisinin iş parçacıkları arasında bile her zaman güvenli olmasını sağlar.

Ek kavramlar

İstemci seçenekleri | Yanıta | erişme Uzun süre çalışan işlemler | Hataları | işleme Tanılama | Alaycı | İstemci ömrü

Örnekler

Event Grid olaylarını Event Grid Konusuna yayımlama

Event Grid'de yayımlama olayları kullanılarak EventGridPublisherClientgerçekleştirilir. Konu başlığında tek bir olay yayımlamak için sağlanan SendEvent/SendEventAsync yöntemi kullanın.

// 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);

Toplu olay yayımlamak için yöntemini kullanın 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'i Event Grid Konusuna Yayımlama

Event Grid'de yayımlama olayları kullanılarak EventGridPublisherClientgerçekleştirilir. Konu başlığında olayları yayımlamak için sağlanan SendEvents/SendEventsAsync yöntemi kullanın.

// 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 olaylarını Event Grid Etki Alanına yayımlama

Olay etki alanı, aynı uygulamayla ilgili çok sayıda Event Grid konusuna yönelik bir yönetim aracıdır. Bunu, binlerce ayrı konuya sahip olabilecek bir meta konu olarak düşünebilirsiniz. Olay etki alanı oluşturduğunuzda, Event Grid'de bir konu oluşturmuş olmanıza benzer bir yayımlama uç noktası verilir.

Olay Etki Alanındaki herhangi bir konuya olay yayımlamak için, olayları özel bir konu için yaptığınız gibi etki alanının uç noktasına gönderin. Tek fark, olayın teslim edilmesi istediğiniz konuyu belirtmeniz gerektiğidir.

// 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 göndermek için CloudEvent kaynağı, etki alanı konusu olarak kullanılır:

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);

Olayları Alma ve Seri Durumdan Çıkarma

Olay işleyicisi olarak davranan birkaç farklı Azure hizmeti vardır.

Not: Event Grid şemasının olay teslimi için Web Kancaları kullanılıyorsa, Event Grid bu uç noktaya olay göndermeye başlamadan önce Web kancası uç noktanızın sahipliğini kanıtlamanızı gerektirir. Olay aboneliği oluşturulurken Event Grid, aşağıda görüldüğü gibi uç noktanıza bir abonelik doğrulama olayı gönderir. El sıkışmasını tamamlama hakkında daha fazla bilgiyi burada bulabilirsiniz: Web kancası olay teslimi. CloudEvents şeması için hizmet, HTTP seçenekleri yöntemini kullanarak bağlantıyı doğrular. Buradan daha fazla bilgi edinin: CloudEvents doğrulaması.

Olaylar olay işleyicisine teslim edildikten sonra JSON yükünün seri durumdan çıkararak olay listesini oluşturabiliriz.

kullanarak EventGridEvent:

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

kullanarak CloudEvent:

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

Olay verilerinin seri durumdan çıkarılması

Buradan, özelliğinde çağrısı ToObjectFromJson<T>() yaparak belirli bir türe seri durumdan çıkararak olay verilerine Data erişebilirsiniz. Doğru türe EventType seri durumdan çıkarabilmek için özelliği (Type CloudEvents için) farklı olayları ayırt etmeye yardımcı olur. Özel olay verileri genel yöntemi ToObjectFromJson<T>()kullanılarak seri durumdan çıkarılmalıdır. Olay verilerinin seri durumdan çıkarılması için özel ObjectSerializer kabul eden bir uzantı yöntemi ToObject<T>() de vardır.

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;
    }
}

kullanarak TryGetSystemEventData():

Çoğunlukla sistem olaylarını bekliyorsanız, tek tek olaylar üzerinde işlem yapmak için desen eşleştirmeyi açmak TryGetSystemEventData() ve kullanmak daha temiz olabilir. Bir olay bir sistem olayı değilse, yöntem false döndürür ve out parametresi null olur.

Uyarı olarak, daha sonra hizmet ve SDK tarafından sistem olayı olarak eklenen bir EventType değeriyle özel bir olay türü kullanıyorsanız, dönüş değeri TryGetSystemEventData olarak falsetruedeğişir. Hizmet tarafından zaten gönderilen ancak henüz SDK'ya eklenmemiş olaylar için kendi özel olaylarınızı önceden oluşturuyorsanız bu durum ortaya çıkabilir. Bu durumda, yükseltmeden sonra kod akışınızın otomatik olarak değişmemesi için özelliğinde Data genel ToObjectFromJson<T> yöntemi kullanmak daha iyidir (elbette, kodunuzu özel modelinizin aksine yeni yayımlanan sistem olay modelini kullanacak şekilde değiştirmek isteyebilirsiniz).

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;
        }
    }
}

Sorun giderme

Hizmet Yanıtları

SendEvents() hizmetten bir HTTP yanıt kodu döndürür. RequestFailedException başarısız istekler için bir hizmet yanıtı olarak oluşturulur. Özel durum, hizmetten döndürülen yanıt kodu hakkında bilgi içerir.

Olay Verilerini Seri Durumdan Çıkarma

  • Olay verileri geçerli JSON değilse, veya ParseManyçağrılırken Parse bir JsonException oluşturulur.
  • Olay şeması seri durumdan çıkarılmakta olan türe karşılık gelmiyorsa (örneğin bir EventGridSchema olayında çağrılması CloudEvent.Parse ), bir ArgumentException oluşturulur.
  • Birden çok olay içeren verilerde çağrılırsa Parse , bir ArgumentException oluşturulur. ParseMany yerine burada kullanılmalıdır.

Konsol günlüğünü ayarlama

Ayrıca, hizmette yaptığınız istekleri daha ayrıntılı bir şekilde incelemek isterseniz konsol günlüğünü kolayca etkinleştirebilirsiniz .

Dağıtılmış İzleme

Event Grid kitaplığı, izlemenin kutudan dağıtımını destekler. CloudEvents belirtiminin izleme dağıtma yönergelerine uymak için kitaplık, dağıtılmış izleme etkinleştirildiğinde ve tracestateExtensionAttributesCloudEvent değerini ayarlar.traceparent Uygulamanızda dağıtılmış izlemeyi etkinleştirme hakkında daha fazla bilgi edinmek için Azure SDK dağıtılmış izleme belgelerine göz atın.

Kubernetes’te Event Grid

Bu kitaplık, Azure Arc kullanılarak Kubernetes'te test edilmiş ve doğrulanmıştır.

Sonraki adımlar

Event Grid istemci kitaplığının yaygın kullanımları için burada daha fazla https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.14.1/sdk/eventgrid/Azure.Messaging.EventGrid/samples bilgi bulabilirsiniz: Event Grid Örnekleri.

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorular veya yorumlarla iletişime geçin opencode@microsoft.com .

İzlenimler