Griglia di eventi di Azure libreria client per Python - versione 4.17.0b1

  • Articolo

Griglia di eventi di Azure è un servizio di routing di eventi intelligente completamente gestito che consente un uso degli eventi uniforme tramite un modello di pubblicazione-sottoscrizione.

Codice | sorgentePacchetto (PyPI) | Pacchetto (Conda) | Documentazione | di riferimento sulle APIDocumentazione | del prodottoCampioni | Changelog

Dichiarazione di non responsabilità

Si tratta di una versione beta di Azure EventGrid EventGridClient, che insieme alla disponibilità generale EventGridPublisherClient. EventGridClient supporta publish_cloud_eventsle operazioni , receive_cloud_events, acknowledge_cloud_eventsrelease_cloud_events, reject_cloud_events, e renew_cloud_event_locks . Per altre informazioni, vedere gli esempi .

Introduzione

Prerequisiti

Installare il pacchetto

Installare la libreria client Griglia di eventi di Azure per Python con pip:

pip install azure-eventgrid

Se si usa l'interfaccia della riga di comando di Azure, sostituire <resource-group-name> e <resource-name> con i propri nomi univoci.

Creare un argomento di Griglia di eventi

az eventgrid topic --create --location <location> --resource-group <resource-group-name> --name <resource-name>

Creare un dominio di Griglia di eventi

az eventgrid domain --create --location <location> --resource-group <resource-group-name> --name <resource-name>

Autenticare il client

Per interagire con il servizio Griglia di eventi, è necessario creare un'istanza di un client. Un endpoint e le credenziali sono necessari per creare un'istanza dell'oggetto client.

Uso di Azure Active Directory (AAD)

Griglia di eventi di Azure fornisce l'integrazione con Azure Active Directory (Azure AD) per l'autenticazione basata sull'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 a utenti, gruppi o applicazioni.

Per inviare eventi a un argomento o a un dominio con , TokenCredentialall'identità autenticata deve essere assegnato il ruolo "Mittente dati EventGrid".

Con il azure-identity pacchetto è possibile autorizzare facilmente le richieste in ambienti di sviluppo e di produzione. Per altre informazioni su Azure Active Directory, vedere READMEazure-identity.

Ad esempio, è possibile usare DefaultAzureCredential per costruire un client che eseguirà l'autenticazione usando Azure Active Directory:

from azure.identity import DefaultAzureCredential
from azure.eventgrid import EventGridPublisherClient, EventGridEvent

default_az_credential = DefaultAzureCredential()
endpoint = os.environ["EVENTGRID_TOPIC_ENDPOINT"]
client = EventGridPublisherClient(endpoint, default_az_credential)

Ricerca dell'endpoint

È possibile trovare l'endpoint dell'argomento all'interno della risorsa Argomento di Griglia di eventi nella portale di Azure. L'aspetto sarà simile al seguente: "https://<event-grid-topic-name>.<topic-location>.eventgrid.azure.net/api/events"

Creare il client con AzureKeyCredential

Per usare una chiave di accesso come credential parametro, passare la chiave come stringa in un'istanza di AzureKeyCredential.

Nota: La chiave di accesso è disponibile nel portale di Azure nel menu "Chiavi di accesso" della risorsa Argomento di Griglia di eventi. Possono anche essere ottenuti tramite l'interfaccia della riga di comando di Azure o la azure-mgmt-eventgrid libreria. Una guida per ottenere le chiavi di accesso è disponibile qui.

import os
from azure.eventgrid import EventGridPublisherClient
from azure.core.credentials import AzureKeyCredential

topic_key = os.environ["EVENTGRID_TOPIC_KEY"]
endpoint = os.environ["EVENTGRID_TOPIC_ENDPOINT"]

credential_key = AzureKeyCredential(topic_key)
client = EventGridPublisherClient(endpoint, credential_key)

Nota: Un client può anche essere autenticato tramite firma di firma di accesso condiviso, usando .AzureSasCredential Un esempio che illustra questa operazione è disponibile qui (async_version).

Nota: Il generate_sas metodo può essere usato per generare una firma di accesso condiviso. Un esempio che illustra questo problema è disponibile qui.

Concetti chiave

Argomento

Un argomento è un canale all'interno del servizio EventGrid per inviare eventi. Lo schema di eventi accettato da un argomento viene deciso in fase di creazione dell'argomento. Se gli eventi di un tipo di schema vengono inviati a un argomento che richiede un tipo di schema diverso, verranno generati errori.

Dominio

Un dominio eventi è uno strumento di gestione per un numero elevato di argomenti di Griglia di eventi correlati alla stessa applicazione. Consentono di pubblicare eventi in migliaia di argomenti. I domini offrono anche il controllo dell'autorizzazione e dell'autenticazione su ogni argomento. Per altre informazioni, vedere Panoramica del dominio eventi.

Quando si crea un dominio eventi, viene reso disponibile un endpoint di pubblicazione per questo dominio. Questo processo è simile alla creazione di un argomento di Griglia di eventi. L'unica differenza è che, quando si pubblica in un dominio, è necessario specificare l'argomento all'interno del dominio a cui si vuole recapitare l'evento.

Schemi degli eventi

Un evento è la quantità minima di informazioni che descrive completamente qualcosa che si è verificato nel sistema. Quando viene creato un argomento o un dominio personalizzato, è necessario specificare lo schema che verrà utilizzato durante la pubblicazione di eventi.

Griglia di eventi supporta più schemi per la codifica degli eventi.

Schema di Griglia di eventi

Anche se è possibile configurare l'argomento per l'uso di uno schema personalizzato, è più comune usare lo schema di 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.

EventGridPublisherClient

EventGridPublisherClient fornisce operazioni per inviare i dati dell'evento a un nome host dell'argomento specificato durante l'inizializzazione del client.

Indipendentemente dallo schema che l'argomento o il dominio è configurato per l'uso, EventGridPublisherClient verrà usato per pubblicare gli eventi. Usare gli eventi di pubblicazione del send metodo.

È possibile inviare i formati di eventi seguenti:

  • Elenco o una singola istanza di EventGridEvent fortemente tipizzato.

  • Rappresentazione dict di un oggetto EventGridEvent serializzato.

  • Elenco o singola istanza di CloudEvent fortemente tipizzato.

  • Rappresentazione dict di un oggetto CloudEvent serializzato.

  • Rappresentazione dict di qualsiasi schema personalizzato.

Per esempi dettagliati, vedere gli esempi .

Nota: È importante sapere se l'argomento supporta CloudEvents o EventGridEvents prima della pubblicazione. Se si invia a un argomento che non supporta lo schema dell'evento inviato, send() genererà un'eccezione.

Argomenti di sistema

Un argomento di sistema in Griglia di eventi rappresenta uno o più eventi pubblicati da servizi di Azure, ad esempio Archiviazione di Azure o Hub eventi di Azure. Ad esempio, un argomento di sistema può rappresentare tutti gli eventi BLOB o solo gli eventi di creazione di BLOB ed eliminazione BLOB pubblicati per un account di archiviazione specifico.

I nomi dei vari tipi di evento per gli eventi di sistema pubblicati in Griglia di eventi di Azure sono disponibili in azure.eventgrid.SystemEventNames. Per un elenco completo degli argomenti di sistema riconoscibili, vedere Argomenti di sistema.

Per altre informazioni sui concetti chiave di Griglia di eventi, vedere Concetti in Griglia di eventi di Azure.

Griglia di eventi in Kubernetes con Azure Arc

Griglia di eventi in Kubernetes con Azure Arc è un'offerta che consente di eseguire Griglia di eventi nel proprio cluster Kubernetes. Questa funzionalità è abilitata dall'uso di Kubernetes con abilitazione di Azure Arc. Tramite Kubernetes con abilitazione di Azure Arc, un cluster Kubernetes supportato si connette ad Azure. Dopo la connessione, è possibile installare Griglia di eventi. Per altre informazioni, vedere qui.

Supporto per gli eventi cloud CNF

A partire dalla versione 4.7.0, questo pacchetto supporta anche la pubblicazione di un evento cloud CNF da https://pypi.org/project/cloudevents/. Sarebbe possibile passare un oggetto CloudEvent da questa libreria all'API send .


from cloudevents.http import CloudEvent

event = CloudEvent(...)

client.send(event)

Esempio

Le sezioni seguenti forniscono diversi frammenti di codice relativi ad alcune delle attività più comuni di Griglia di eventi, tra cui:

Inviare un evento di Griglia di eventi

In questo esempio viene pubblicato un evento di Griglia di eventi.

import os
from azure.core.credentials import AzureKeyCredential
from azure.eventgrid import EventGridPublisherClient, EventGridEvent

key = os.environ["EG_ACCESS_KEY"]
endpoint = os.environ["EG_TOPIC_HOSTNAME"]

event = EventGridEvent(
    data={"team": "azure-sdk"},
    subject="Door1",
    event_type="Azure.Sdk.Demo",
    data_version="2.0"
)

credential = AzureKeyCredential(key)
client = EventGridPublisherClient(endpoint, credential)

client.send(event)

Inviare un evento cloud

Questo esempio pubblica un evento Cloud.

import os
from azure.core.credentials import AzureKeyCredential
from azure.core.messaging import CloudEvent
from azure.eventgrid import EventGridPublisherClient

key = os.environ["CLOUD_ACCESS_KEY"]
endpoint = os.environ["CLOUD_TOPIC_HOSTNAME"]

event = CloudEvent(
    type="Azure.Sdk.Sample",
    source="https://egsample.dev/sampleevent",
    data={"team": "azure-sdk"}
)

credential = AzureKeyCredential(key)
client = EventGridPublisherClient(endpoint, credential)

client.send(event)

Inviare più eventi

È possibile inviare eventi come batch quando si inviano più eventi a un argomento o a un dominio. In questo esempio viene inviato un elenco di CloudEvents usando il metodo send.

AVVISO: Quando si invia un elenco di più eventi contemporaneamente, l'iterazione e l'invio di ogni evento non comporterà prestazioni ottimali. Per ottenere prestazioni ottimali, è consigliabile inviare un elenco di eventi.

import os
from azure.core.credentials import AzureKeyCredential
from azure.core.messaging import CloudEvent
from azure.eventgrid import EventGridPublisherClient

key = os.environ["CLOUD_ACCESS_KEY"]
endpoint = os.environ["CLOUD_TOPIC_HOSTNAME"]

event0 = CloudEvent(
    type="Azure.Sdk.Sample",
    source="https://egsample.dev/sampleevent",
    data={"team": "azure-sdk"}
)
event1 = CloudEvent(
    type="Azure.Sdk.Sample",
    source="https://egsample.dev/sampleevent",
    data={"team2": "azure-eventgrid"}
)

events = [event0, event1]

credential = AzureKeyCredential(key)
client = EventGridPublisherClient(endpoint, credential)

client.send(events)

Inviare eventi come dizionari

È anche possibile usare una rappresentazione dict dei rispettivi modelli serializzati per pubblicare CloudEvent o EventGridEvent a parte gli oggetti fortemente tipizzati.

Usare una rappresentazione simile a ct per inviare a un argomento con schema personalizzato, come illustrato di seguito.

import os
import uuid
import datetime as dt
from msrest.serialization import UTC
from azure.core.credentials import AzureKeyCredential
from azure.eventgrid import EventGridPublisherClient

key = os.environ["CUSTOM_SCHEMA_ACCESS_KEY"]
endpoint = os.environ["CUSTOM_SCHEMA_TOPIC_HOSTNAME"]

event = custom_schema_event = {
    "customSubject": "sample",
    "customEventType": "sample.event",
    "customDataVersion": "2.0",
    "customId": uuid.uuid4(),
    "customEventTime": dt.datetime.now(UTC()).isoformat(),
    "customData": "sample data"
    }

credential = AzureKeyCredential(key)
client = EventGridPublisherClient(endpoint, credential)

client.send(event)

Utilizzare dalla coda di archiviazione

Questo esempio usa un messaggio ricevuto dalla coda di archiviazione e lo deserializza in un oggetto CloudEvent.

from azure.core.messaging import CloudEvent
from azure.storage.queue import QueueServiceClient, BinaryBase64DecodePolicy
import os
import json

# all types of CloudEvents below produce same DeserializedEvent
connection_str = os.environ['STORAGE_QUEUE_CONN_STR']
queue_name = os.environ['STORAGE_QUEUE_NAME']

with QueueServiceClient.from_connection_string(connection_str) as qsc:
    payload =  qsc.get_queue_client(
        queue=queue_name,
        message_decode_policy=BinaryBase64DecodePolicy()
        ).peek_messages()

    ## deserialize payload into a list of typed Events
    events = [CloudEvent.from_dict(json.loads(msg.content)) for msg in payload]

Utilizzare dal bus di servizio

In questo esempio viene utilizzato un messaggio di payload ricevuto da ServiceBus e lo deserializza in un oggetto EventGridEvent.

from azure.eventgrid import EventGridEvent
from azure.servicebus import ServiceBusClient
import os
import json

# all types of EventGridEvents below produce same DeserializedEvent
connection_str = os.environ['SERVICE_BUS_CONN_STR']
queue_name = os.environ['SERVICE_BUS_QUEUE_NAME']

with ServiceBusClient.from_connection_string(connection_str) as sb_client:
    payload =  sb_client.get_queue_receiver(queue_name).receive_messages()

    ## deserialize payload into a list of typed Events
    events = [EventGridEvent.from_dict(json.loads(next(msg.body).decode('utf-8'))) for msg in payload]

Traccia distribuita con EventGrid

È possibile usare OpenTelemetry per Python come di consueto con EventGrid perché è compatibile con l'integrazione della traccia di azure-core.

Ecco un esempio di uso di OpenTelemetry per tracciare l'invio di un CloudEvent.

Prima di tutto, impostare OpenTelemetry come plug-in di traccia abilitato per EventGrid.

from azure.core.settings import settings
from azure.core.tracing.ext.opentelemetry_span import OpenTelemetrySpan

settings.tracing_implementation = OpenTelemetrySpan

Uso regolare dei dati di telemetria aperti da qui. Per informazioni dettagliate, vedere OpenTelemetry . In questo esempio viene usato un semplice utilità di esportazione della console per esportare le tracce. Qualsiasi utilità di esportazione può essere usata qui, tra cui azure-monitor-opentelemetry-exporter, jaegere zipkin così via.

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter
from opentelemetry.sdk.trace.export import SimpleSpanProcessor  # this requires opentelemetry >= 1.0.0

# Simple console exporter
exporter = ConsoleSpanExporter()

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)
trace.get_tracer_provider().add_span_processor(
    SimpleSpanProcessor(exporter)
)

Dopo aver tracer impostato e exporter , seguire l'esempio seguente per iniziare a raccogliere tracce durante l'uso EventGridPublisherClient del send metodo da per inviare un oggetto CloudEvent.

import os
from azure.eventgrid import EventGridPublisherClient
from azure.core.messaging import CloudEvent
from azure.core.credentials import AzureKeyCredential

hostname = os.environ['CLOUD_TOPIC_HOSTNAME']
key = AzureKeyCredential(os.environ['CLOUD_ACCESS_KEY'])
cloud_event = CloudEvent(
    source = 'demo',
    type = 'sdk.demo',
    data = {'test': 'hello'},
)
with tracer.start_as_current_span(name="MyApplication"):
    client = EventGridPublisherClient(hostname, key)
    client.send(cloud_event)

Risoluzione dei problemi

  • Abilitare azure.eventgrid il logger per raccogliere tracce dalla libreria.

Generale

La libreria client di Griglia di eventi genererà eccezioni definite in Azure Core.

Registrazione

Questa libreria usa la libreria di registrazione standard per la registrazione. Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a livello di INFO.

Configurazione facoltativa

Gli argomenti di parole chiave facoltativi possono essere passati al client e al livello di operazione. La documentazione di riferimento di azure-core descrive le configurazioni disponibili per tentativi, registrazione, protocolli di trasporto e altro ancora.

Passaggi successivi

La sezione seguente fornisce diversi frammenti di codice che illustrano i modelli comuni usati nell'API Python di Griglia di eventi.

Altro codice di esempio

Questi esempi di codice illustrano le operazioni comuni degli scenari campione con la libreria client Griglia di eventi di Azure.

Gli esempi seguenti illustrano la pubblicazione e l'utilizzo dict di rappresentazioni di EventGridEvents e CloudEvents.

Altri esempi sono disponibili qui.

  • Altri esempi relativi allo scenario di invio sono disponibili qui.
  • Per visualizzare altri esempi relativi all'utilizzo di un payload da diversi servizi di messaggistica come oggetto tipizzato, vedere Utilizzare esempi

Documentazione aggiuntiva

Per una documentazione più completa su Griglia di eventi di Azure, vedere la documentazione di Griglia di eventi su docs.microsoft.com.

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, visitare 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.