Megosztás a következőn keresztül:

Azure Event Grid ügyfélkódtár a .NET-hez – 4.14.1-es verzió

  • Cikk

Az Azure Event Griddel könnyen létrehozhat eseményalapú architektúrával rendelkező alkalmazásokat. Az Event Grid szolgáltatás teljes mértékben kezeli az események minden útvonalát bármely forrásból, bármilyen célhelyre, bármilyen alkalmazáshoz. Az Azure-szolgáltatásesemények és az egyéni események közvetlenül közzétehetők a szolgáltatásban, ahol az események ezután szűrhetők és elküldhetők különböző címzetteknek, például beépített kezelőknek vagy egyéni webhookoknak. További információ a Azure Event Grid: Mi az az Event Grid?

Használja az ügyfélkódtárat a Azure Event Grid a következőhöz:

Első lépések

A csomag telepítése

Telepítse az ügyfélkódtárat a NuGetből:

dotnet add package Azure.Messaging.EventGrid

Előfeltételek

Egyéni Event Grid-témakörrel vagy -tartománnyal rendelkező Azure-előfizetéssel és Azure-erőforráscsoporttal kell rendelkeznie. Kövesse ezt a részletes oktatóanyagot az Event Grid-erőforrás-szolgáltató regisztrálásához, és hozzon létre Event Grid-témaköröket a Azure Portal használatával. Hasonló oktatóanyag érhető el az Azure CLI használatával.

Az ügyfél hitelesítése

Ahhoz, hogy az ügyfélkódtár egy témakört vagy tartományt használhasson, szüksége lesz az endpoint Event Grid-témakörre és egy credential, amely a témakör hozzáférési kulcsával hozható létre.

Az Event Grid-témakör végpontját az Azure Portalon vagy az alábbi Azure CLI-kódrészlet használatával találja meg.

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

A hozzáférési kulcs a portálon vagy az alábbi Azure CLI-kódrészlet használatával is megtalálható:

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

Hitelesítés témakör hozzáférési kulcsával

Miután megkapta a hozzáférési kulcsot és a témakörvégpontot, az alábbiak szerint hozhatja létre a közzétevő ügyfelet:

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

Hitelesítés megosztott hozzáférésű jogosultságkóddal

Az Event Grid támogatja a közös hozzáférésű jogosultságkóddal történő hitelesítést is, amely lehetővé teszi, hogy hozzáférést biztosítson egy adott időpontig lejáró erőforráshoz a hozzáférési kulcs megosztása nélkül. Általában az a munkafolyamat, hogy az egyik alkalmazás létrehozza az SAS-sztringet, és átadja a sztringet egy másik alkalmazásnak, amely felhasználná a sztringet. Hozza létre az SAS-t:

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

Ezt a fogyasztó szemszögéből a következőképpen használná fel:

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

EventGridPublisherClient a konfigurálási beállítások egy készletét is elfogadja a segítségével EventGridPublisherClientOptions. Megadhat például egy egyéni szerializálót, amellyel szerializálhatja az eseményadatokat a JSON-ra.

Hitelesítés az Azure Active Directory használatával

Azure Event Grid integrációt biztosít az Azure Active Directoryval (Azure AD) a kérések identitásalapú hitelesítéséhez. A Azure AD szerepköralapú hozzáférés-vezérléssel (RBAC) hozzáférést biztosíthat a Azure Event Grid erőforrásokhoz a felhasználók, csoportok vagy alkalmazások számára. Az Azure Identity-kódtár egyszerű Azure Active Directory-támogatást nyújt a hitelesítéshez.

Ha az Azure Active Directory használatával szeretne eseményeket küldeni egy témakörbe vagy tartományba, a hitelesített identitáshoz hozzá kell rendelni az "EventGrid Data Sender" szerepkört.

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

Fő fogalmak

További információ az Event Grid általános fogalmairól: A Azure Event Grid fogalmai.

EventGridPublisherClient

A közzétevő eseményeket küld az Event Grid szolgáltatásnak. A Microsoft több Azure-szolgáltatás eseményeit teszi közzé. Az eseményeket a saját alkalmazásából teheti közzé a EventGridPublisherClientparanccsal.

Eseménysémák

Az esemény a legkisebb mennyiségű információ, amely teljes mértékben leírja a rendszerben történteket. Az Event Grid több sémát is támogat az események kódolásához. Egyéni témakör vagy tartomány létrehozásakor meg kell adnia azt a sémát, amelyet az események közzétételekor használni fog.

Event Grid-séma

Bár a témakört egyéni séma használatára konfigurálhatja, a már definiált Event Grid-séma használata gyakoribb. Itt tekintse meg a specifikációkat és követelményeket.

CloudEvents v1.0 séma

Egy másik lehetőség a CloudEvents v1.0 séma használata. A CloudEvents egy Cloud Native Computing Foundation-projekt, amely egy specifikációt állít elő az eseményadatok általános leírásához. A CloudEvents szolgáltatásösszesítője itt található.

Függetlenül attól, hogy a témakör vagy tartomány milyen sémát használ, EventGridPublisherClient a rendszer események közzétételére fogja használni. A vagy SendEventsAsync metódust SendEvents használja a közzétételhez.

Eseménykézbesítés

Az Event Grid által a fogyasztóknak küldött események JSON-ként lesznek kézbesítve. Attól függően, hogy milyen típusú fogyasztóhoz jut el, az Event Grid szolgáltatás egy vagy több eseményt is kézbesíthet egyetlen hasznos adat részeként. Az események kezelése eltérő lesz attól függően, hogy az esemény milyen sémával lett kézbesítve. Az általános minta azonban változatlan marad:

  • Események elemzése JSON-ból egyéni eseményekbe. Az eseményséma (Event Grid vagy CloudEvents) alapján mostantól hozzáférhet az esemény alapvető információihoz a borítékon (az összes eseményhez elérhető tulajdonságok, például az eseményidő és a típus).
  • Deszerializálja az eseményadatokat. Adott vagy EventGridEventCloudEvent, a felhasználó megpróbálhat hozzáférni az esemény hasznos adataihoz vagy adataihoz, ha deszerializál egy adott típust. Ezen a ponton megadhat egy egyéni szerializálót az adatok helyes dekódolásához.

Menetbiztonság

Garantáljuk, hogy minden ügyfélpéldány-metódus szálbiztos és független egymástól (iránymutatás). Ez biztosítja, hogy az ügyfélpéldányok újrafelhasználására vonatkozó javaslat mindig biztonságos legyen, még a szálak között is.

További fogalmak

Ügyfélbeállítások | A válasz | elérése Hosszú ideig futó műveletek | Hibák | kezelése Diagnosztika | Gúnyos | Ügyfélélettartam

Példák

Event Grid-események közzététele egy Event Grid-témakörben

Az események Event Gridben való közzététele a paranccsal történik.EventGridPublisherClient A megadott SendEvent/SendEventAsync módszerrel egyetlen eseményt tehet közzé a témakörben.

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

Az események kötegének közzétételéhez használja a metódust 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 közzététele Event Grid-témakörben

Az események Event Gridben való közzététele a paranccsal történik.EventGridPublisherClient A megadott SendEvents/SendEventsAsync módszerrel közzéteheti az eseményeket a témakörben.

// 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-események közzététele egy Event Grid-tartományban

Az eseménytartomány egy olyan felügyeleti eszköz, amely számos, ugyanahhoz az alkalmazáshoz kapcsolódó Event Grid-témakörhöz használható. Úgy tekinthet rá, mint egy metatémakörre, amely több ezer különálló témakört tartalmazhat. Eseménytartomány létrehozásakor egy olyan közzétételi végpontot kap, amely hasonló ahhoz, mintha az Event Gridben létrehozott volna egy témakört.

Ha eseményeket szeretne közzétenni egy eseménytartomány bármely témakörében, küldje le az eseményeket a tartomány végpontjára ugyanúgy, mint egy egyéni témakör esetében. Az egyetlen különbség az, hogy meg kell adnia azt a témakört, amelybe az eseményt el szeretné juttatni.

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

A CloudEvents küldéséhez a CloudEvent forrást használja tartománytémakörként:

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

Események fogadása és deszerializálása

Számos különböző Azure-szolgáltatás működik eseménykezelőként.

Megjegyzés: Ha webhookokat használ az Event Grid-séma eseménykézbesítéséhez, az Event Grid megköveteli, hogy igazolja a Webhook-végpont tulajdonjogát, mielőtt elkezdi az eseményeket az adott végpontnak kézbesíteni. Az esemény-előfizetés létrehozásakor az Event Grid egy előfizetés-érvényesítési eseményt küld a végpontnak az alább látható módon. További információ a kézfogás elvégzéséről itt: Webhook eseménykézbesítés. A CloudEvents-séma esetében a szolgáltatás a HTTP-beállítások metódusával ellenőrzi a kapcsolatot. További információ: CloudEvents-ellenőrzés.

Miután az eseményeket az eseménykezelőnek kézbesítettük, deszerializálhatjuk a JSON hasznos adatait egy eseménylistába.

A használata EventGridEvent:

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

A használata CloudEvent:

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

Eseményadatok deszerializálása

Innen elérheti az eseményadatokat úgy, hogy deszerializálja egy adott típusra a Data tulajdonság meghívásávalToObjectFromJson<T>(). A megfelelő típusra való deszerializáláshoz a EventType (Type CloudEvents esetében) tulajdonság segít megkülönböztetni a különböző eseményeket. Az egyéni eseményadatokat deszerializálni kell az általános módszerrel ToObjectFromJson<T>(). Létezik egy bővítménymetódus ToObject<T>() is, amely elfogad egy egyénit ObjectSerializer az eseményadatok deszerializálásához.

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

A használatával TryGetSystemEventData():

Ha többnyire rendszereseményekre számít, előfordulhat, hogy tisztábban kapcsol be TryGetSystemEventData() , és mintaegyeztetés használatával reagál az egyes eseményekre. Ha egy esemény nem rendszeresemény, a metódus hamis értéket ad vissza, a kimenő paraméter pedig null értékű lesz.

Ha egyéni eseménytípust használ egy EventType értékkel, amelyet később a szolgáltatás és az SDK rendszereseményként ad hozzá, a visszatérési TryGetSystemEventData értéke értékről false értékre trueváltozik. Ez akkor fordulhat elő, ha előre létrehozza a saját egyéni eseményeit a szolgáltatás által már elküldött, de még nem az SDK-hoz még nem hozzáadott eseményekhez. Ebben az esetben érdemesebb az általános ToObjectFromJson<T> metódust használni a Data tulajdonságon, hogy a kódfolyam ne változzon automatikusan a frissítés után (természetesen érdemes lehet módosítani a kódot úgy, hogy az az újonnan kiadott rendszeresemény-modellt használja az egyéni modell helyett).

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

Hibaelhárítás

Szolgáltatásválaszok

SendEvents() HTTP-válaszkódot ad vissza a szolgáltatástól. Az A RequestFailedException szolgáltatásválaszként lesz küldve a sikertelen kérések esetén. A kivétel információt tartalmaz arról, hogy milyen válaszkódot adott vissza a szolgáltatás.

Eseményadatok deszerializálása

  • Ha az eseményadatok érvénytelen JSON-ként vannak megadva, a vagy a hívásakor ParseParseManyegy JsonException jelenik meg.
  • Ha az eseményséma nem felel meg a deszerializált típusnak (például egy EventGridSchema-esemény meghívása CloudEvent.Parse ), a rendszer egy ArgumentException hibát ad vissza.
  • Ha Parse több eseményt tartalmazó adatokra van meghívva, a függvény egy ArgumentException értéket ad. ParseMany itt kell használni.

Konzolnaplózás beállítása

A konzolnaplózást is egyszerűen engedélyezheti, ha mélyebbre szeretné ásni a szolgáltatással kapcsolatos kéréseket.

Elosztott nyomkövetés

Az Event Grid-kódtár támogatja a nyomkövetés kiosztását a dobozból. Annak érdekében, hogy megfeleljen a CloudEvents nyomkövetés terjesztésére vonatkozó útmutatójának , a kódtár beállítja a traceparent és tracestate a ExtensionAttributesCloudEvent értékét, amikor az elosztott nyomkövetés engedélyezve van. Ha többet szeretne megtudni az elosztott nyomkövetés alkalmazáson belüli engedélyezéséről, tekintse meg az Azure SDK elosztott nyomkövetési dokumentációját.

Event Grid a Kubernetesen

Ezt a kódtárat teszteltük és ellenőriztük a Kubernetesben az Azure Arc használatával.

Következő lépések

Az https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.14.1/sdk/eventgrid/Azure.Messaging.EventGrid/samples Event Grid-ügyfélkódtár gyakori használati módjai: Event Grid-minták.

Közreműködés

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. Részletekért látogasson el ide: https://cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes olyan tárházban, amely a CLA-t használja.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.

Megjelenések