Condividi tramite

Griglia di eventi di Azure libreria client per .NET - versione 4.14.1

  • Articolo

Griglia di eventi di Azure consente di compilare facilmente applicazioni con architetture basate su eventi. Il servizio Griglia di eventi gestisce completamente tutti i routing di eventi da qualsiasi origine, a qualsiasi destinazione, per qualsiasi applicazione. Gli eventi del servizio di Azure e gli eventi personalizzati possono essere pubblicati direttamente nel servizio, in cui gli eventi possono quindi essere filtrati e inviati a vari destinatari, ad esempio gestori predefiniti o webhook personalizzati. Per altre informazioni su Griglia di eventi di Azure: Che cos'è Griglia di eventi?

Usare la libreria client per Griglia di eventi di Azure per:

  • Pubblicare eventi nel servizio Griglia di eventi usando l'evento Griglia di eventi, l'evento cloud 1.0 o gli schemi personalizzati

  • Utilizzare gli eventi recapitati ai gestori eventi

  • Generare token di firma di accesso condiviso per autenticare gli eventi di pubblicazione client in Griglia di eventi di Azure argomenti

    Codice | sorgente Pacchetto (NuGet) | Documentazione di | riferimento sulle API Documentazione | del prodotto Campioni | Guida alla migrazione

Introduzione

Installare il pacchetto

Installare la libreria client da NuGet:

dotnet add package Azure.Messaging.EventGrid

Prerequisiti

È necessario disporre di una sottoscrizione di Azure e di un gruppo di risorse di Azure con un argomento o un dominio di Griglia di eventi personalizzato. Seguire questa esercitazione dettagliata per registrare il provider di risorse griglia di eventi e creare argomenti di Griglia di eventi usando la portale di Azure. È disponibile un'esercitazione simile con l'interfaccia della riga di comando di Azure.

Autenticare il client

Per consentire alla libreria client di interagire con un argomento o un dominio, sarà necessario l'argomento endpoint griglia di eventi e un credentialoggetto , che può essere creato usando la chiave di accesso dell'argomento.

È possibile trovare l'endpoint per l'argomento Griglia di eventi nel portale di Azure o usando il frammento di interfaccia della riga di comando di Azure seguente.

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

La chiave di accesso è disponibile anche tramite il portale o usando il frammento di interfaccia della riga di comando di Azure seguente:

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

Eseguire l'autenticazione con la chiave di accesso all'argomento

Dopo aver ottenuto la chiave di accesso e l'endpoint dell'argomento, è possibile creare il client di pubblicazione come indicato di seguito:

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

Eseguire l'autenticazione con la firma di accesso condiviso

Griglia di eventi supporta anche l'autenticazione con una firma di accesso condiviso che consente di fornire l'accesso a una risorsa che scade entro un determinato periodo di tempo senza condividere la chiave di accesso. In genere, il flusso di lavoro sarebbe che un'applicazione genererebbe la stringa sas e disegni la stringa a un'altra applicazione che utilizzerebbe la stringa. Generare la firma di accesso condiviso:

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

Ecco come verrà usato dal punto di vista del consumer:

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

EventGridPublisherClient accetta anche un set di opzioni di configurazione tramite EventGridPublisherClientOptions. Ad esempio, è possibile specificare un serializzatore personalizzato che verrà usato per serializzare i dati dell'evento in JSON.

Eseguire l'autenticazione con Azure Active Directory

Griglia di eventi di Azure fornisce l'integrazione con Azure Active Directory (Azure AD) per l'autenticazione basata su identità delle richieste. Con Azure AD è possibile usare il controllo degli accessi in base al ruolo per concedere l'accesso alle risorse Griglia di eventi di Azure agli utenti, ai gruppi o alle applicazioni. La libreria di identità di Azure offre un supporto semplice di Azure Active Directory per l'autenticazione.

Per inviare eventi a un argomento o a un dominio usando Azure Active Directory, l'identità autenticata deve avere il ruolo "Mittente dati EventGrid".

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

Concetti chiave

Per informazioni sui concetti generali di Griglia di eventi: concetti in Griglia di eventi di Azure.

EventGridPublisherClient

Un server di pubblicazione invia eventi al servizio Griglia di eventi. Microsoft pubblica gli eventi per diversi servizi di Azure. È possibile pubblicare eventi dalla propria applicazione usando .EventGridPublisherClient

Schemi degli eventi

Un evento è la quantità più piccola di informazioni che descrive completamente qualcosa che è successo nel sistema. Griglia di eventi supporta più schemi per gli eventi di codifica. Quando viene creato un argomento o un dominio personalizzato, specificare lo schema che verrà usato durante la pubblicazione di eventi.

Schema di Griglia di eventi

Anche se è possibile configurare l'argomento per usare uno schema personalizzato, è più comune usare lo schema griglia di eventi già definito. Vedere le specifiche e i requisiti qui.

Schema CloudEvents v1.0

Un'altra opzione consiste nell'usare lo schema CloudEvents v1.0. CloudEvents è un progetto Cloud Native Computing Foundation che produce una specifica per descrivere i dati degli eventi in modo comune. Il riepilogo del servizio di CloudEvents è disponibile qui.

Indipendentemente dallo schema configurato per l'uso dell'argomento o del dominio, EventGridPublisherClient verrà usato per pubblicare gli eventi. Usare il SendEvents metodo o SendEventsAsync per la pubblicazione.

Recapito di eventi

Gli eventi recapitati ai consumer da Griglia di eventi vengono recapitati come JSON. A seconda del tipo di consumer a cui viene recapitato, il servizio Griglia di eventi può recapitare uno o più eventi come parte di un singolo payload. La gestione degli eventi sarà diversa in base allo schema che l'evento è stato recapitato come. Tuttavia, il modello generale rimarrà lo stesso:

  • Analizzare gli eventi da JSON a singoli eventi. In base allo schema degli eventi (Griglia di eventi o CloudEvents), è ora possibile accedere alle informazioni di base sull'evento nella busta (proprietà presenti per tutti gli eventi, ad esempio l'ora e il tipo di evento).
  • Deserializzare i dati dell'evento. Dato un EventGridEvent oggetto o CloudEvent, l'utente può tentare di accedere al payload dell'evento o ai dati, deserializzando in un tipo specifico. È possibile specificare un serializzatore personalizzato a questo punto per decodificare correttamente i dati.

Thread safety

Si garantisce che tutti i metodi di istanza client siano thread-safe e indipendenti tra loro (linee guida). Ciò garantisce che la raccomandazione di riutilizzare le istanze client sia sempre sicura, anche tra thread.

Concetti aggiuntivi

Opzioni | client Accesso alla risposta | Operazioni | a esecuzione prolungataGestione degli errori | Diagnostica | Beffardo | Durata client

Esempio

Pubblicare eventi griglia di eventi in un argomento griglia di eventi

La pubblicazione di eventi in Griglia di eventi viene eseguita usando .EventGridPublisherClient Usare il metodo fornito SendEvent/SendEventAsync per pubblicare un singolo evento nell'argomento.

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

Per pubblicare un batch di eventi, usare il SendEvents/SendEventsAsync metodo .

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

Pubblicare CloudEvents in un argomento griglia di eventi

La pubblicazione di eventi in Griglia di eventi viene eseguita usando .EventGridPublisherClient Usare il metodo fornito SendEvents/SendEventsAsync per pubblicare gli eventi nell'argomento.

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

Pubblicare eventi griglia di eventi in un dominio griglia di eventi

Un dominio di eventi è uno strumento di gestione per un numero elevato di argomenti di Griglia di eventi correlati alla stessa applicazione. Si può paragonare a un meta-argomento che può avere migliaia di singoli argomenti. Quando si crea un dominio eventi, si ottiene un endpoint di pubblicazione come se si fosse creato un argomento in Griglia di eventi.

Per pubblicare eventi in qualsiasi argomento in un dominio di eventi, eseguire il push degli eventi nell'endpoint del dominio allo stesso modo in cui si farebbe per un argomento personalizzato. L'unica differenza è che è necessario specificare l'argomento al quale si vuole recapitare l'evento.

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

Per l'invio di CloudEvent, l'origine CloudEvent viene usata come argomento di dominio:

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

Ricezione e deserializzazione di eventi

Esistono diversi servizi di Azure che fungono da gestori eventi.

Nota: se si usano webhook per la distribuzione di eventi dello schema griglia di eventi, Griglia di eventi richiede di dimostrare la proprietà dell'endpoint webhook prima di iniziare a distribuire eventi a tale endpoint. Al momento della creazione della sottoscrizione eventi, Griglia di eventi invia un evento di convalida della sottoscrizione all'endpoint, come illustrato di seguito. Altre informazioni sul completamento dell'handshake qui: recapito eventi Webhook. Per lo schema CloudEvents, il servizio convalida la connessione usando il metodo di opzioni HTTP. Altre informazioni sono disponibili qui: Convalida di CloudEvents.

Una volta recapitati gli eventi al gestore eventi, è possibile deserializzare il payload JSON in un elenco di eventi.

Utilizzo di EventGridEvent:

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

Utilizzo di CloudEvent:

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

Deserializzazione dei dati degli eventi

Da qui, è possibile accedere ai dati dell'evento deserializzando a un tipo specifico chiamando ToObjectFromJson<T>() la Data proprietà. Per deserializzare il tipo corretto, la EventType proprietà (Type per CloudEvents) consente di distinguere tra eventi diversi. I dati degli eventi personalizzati devono essere deserializzati usando il metodo generico ToObjectFromJson<T>(). Esiste anche un metodo ToObject<T>() di estensione che accetta un oggetto personalizzato ObjectSerializer per deserializzare i dati dell'evento.

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

Utilizzo di TryGetSystemEventData():

Se ci si aspetta principalmente eventi di sistema, potrebbe essere più pulito attivare TryGetSystemEventData() e usare la corrispondenza dei modelli per agire sui singoli eventi. Se un evento non è un evento di sistema, il metodo restituirà false e il parametro out sarà Null.

Come avviso, se si usa un tipo di evento personalizzato con un valore EventType che successivamente viene aggiunto come evento di sistema dal servizio e dall'SDK, il valore restituito di TryGetSystemEventData cambierà da false a true. Ciò potrebbe verificarsi se si creano in modo preliminare gli eventi personalizzati per gli eventi già inviati dal servizio, ma non sono ancora stati aggiunti all'SDK. In questo caso, è preferibile usare il metodo generico ToObjectFromJson<T> nella Data proprietà in modo che il flusso di codice non venga modificato automaticamente dopo l'aggiornamento (naturalmente, è comunque consigliabile modificare il codice per utilizzare il modello di eventi di sistema appena rilasciato anziché il modello personalizzato).

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

Risoluzione dei problemi

Risposte al servizio

SendEvents() restituisce un codice di risposta HTTP dal servizio. Viene RequestFailedException generata una risposta come servizio per eventuali richieste non riuscite. L'eccezione contiene informazioni sul codice di risposta restituito dal servizio.

Deserializzazione dei dati degli eventi

  • Se i dati dell'evento non sono validi JSON, verrà generato un JsonException oggetto quando si chiama Parse o ParseMany.
  • Se lo schema dell'evento non corrisponde al tipo a cui viene deserializzato (ad esempio la chiamata CloudEvent.Parse a un evento EventGridSchema), viene generato un ArgumentException oggetto .
  • Se Parse viene chiamato sui dati che contengono più eventi, viene generato un ArgumentException oggetto . ParseMany deve essere usato qui.

Configurazione della registrazione della console

È anche possibile abilitare facilmente la registrazione della console se si vuole approfondire le richieste eseguite con il servizio.

Traccia distribuita

La libreria Griglia di eventi supporta la distribuzione della traccia nella casella. Per rispettare le indicazioni della specifica CloudEvents sulla distribuzione della traccia, la libreria imposta e traceparenttracestate su ExtensionAttributes un CloudEvent oggetto quando è abilitata la traccia distribuita. Per altre informazioni su come abilitare la traccia distribuita nell'applicazione, vedere la documentazione di traccia distribuita di Azure SDK.

Griglia di eventi in Kubernetes

Questa libreria è stata testata e convalidata in Kubernetes usando Azure Arc.

Passaggi successivi

Per l'utilizzo comune della libreria client griglia di eventi, vedere altre https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.14.1/sdk/eventgrid/Azure.Messaging.EventGrid/samples informazioni: Esempi di Griglia di eventi.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Impression