Griglia di eventi di Azure libreria client per Python - versione 4.16.0

  • 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

Introduzione

Prerequisiti

Installare il pacchetto

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

pip install azure-eventgrid
  • È necessario un argomento o un dominio di Griglia di eventi esistente. È possibile creare la risorsa usando il portale di Azure o l'interfaccia della riga di comando di Azure

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

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

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

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 nella risorsa Argomento griglia di eventi nella portale di Azure. Questo 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 può essere trovata nel portale di Azure nel menu "Chiavi di accesso" della risorsa Argomento 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 l'oggetto AzureSasCredential. Un esempio che illustra questo, è disponibile qui (async_version).

Nota: Il generate_sas metodo può essere usato per generare una firma di accesso condiviso. Un esempio che illustra questa operazione può essere vista qui.

Concetti chiave

Argomento

Un argomento è un canale all'interno del servizio EventGrid per inviare eventi. Lo schema dell'evento 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 di 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 forniscono anche l'autorizzazione e il controllo di autenticazione su ogni argomento. Per altre informazioni, visitare Panoramica del dominio eventi.

Quando si crea un dominio di eventi, viene reso disponibile un endpoint di pubblicazione per questo dominio. Questo processo è simile alla creazione di un argomento 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 che l'evento venga recapitato.

Schemi degli eventi

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

Griglia di eventi supporta più schemi per gli eventi di codifica.

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.

EventGridPublisherClient

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

Indipendentemente dallo schema configurato per l'uso dell'argomento o del dominio, EventGridPublisherClient verrà usato per pubblicare gli eventi. Usare gli eventi di pubblicazione dei send metodi.

I formati seguenti di eventi possono essere inviati:

  • Elenco o una singola istanza di EventGridEvents fortemente tipizzata.

  • Rappresentazione dict di un oggetto EventGridEvent serializzato.

  • Elenco o una singola istanza di CloudEvents fortemente tipizzata.

  • 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 dai 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 e 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, visitare 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 cluster Kubernetes. Questa funzionalità è abilitata dall'uso di Kubernetes abilitato per Azure Arc. Tramite Kubernetes abilitato per Azure Arc, un cluster Kubernetes supportato si connette ad Azure. Dopo la connessione, è possibile installare Griglia di eventi in esso. Per altre informazioni, vedere qui.

Supporto per gli eventi cloud DI CNF

A partire da v4.7.0, questo pacchetto supporta anche la pubblicazione di un evento cloud CNCF da https://pypi.org/project/cloudevents/. È 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 che coprono alcune delle attività più comuni di Griglia di eventi, tra cui:

Inviare un evento griglia di eventi

In questo esempio viene pubblicato un evento 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

In questo esempio viene pubblicato 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 alla volta, l'iterazione e l'invio di ogni evento non comporta 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

Una rappresentazione dict dei rispettivi modelli serializzati può essere usata anche per pubblicare CloudEvent(s) o EventGridEvent(s) 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)

Usare dalla coda di archiviazione

In questo esempio viene usato 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]

Utilizzo dal bus di servizio

In questo esempio viene usato 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.

Impostare Prima di tutto 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

Utilizzo regolare dei dati di telemetria aperti da qui. Per informazioni dettagliate , vedere OpenTelemetry . In questo esempio viene usato un semplice esportazione della console per esportare le tracce. Qualsiasi esportatrice può essere usata qui, tra cui azure-monitor-opentelemetry-exporter, jaegerzipkin e 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 impostato eexporter, seguire l'esempio tracer seguente per iniziare a raccogliere tracce durante l'uso del send metodo da EventGridPublisherClient 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 logger per raccogliere tracce dalla libreria.

Generale

La libreria client 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 delle parole chiave facoltativi possono essere passati al client e a 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 griglia di eventi.

Altro codice di esempio

Questi esempi di codice mostrano operazioni di scenario campione comuni 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 correlati allo scenario di invio possono essere visualizzati qui.
  • Per visualizzare altri esempi relativi all'utilizzo di un payload da diversi servizi di messaggistica come oggetto tipizzato, vedere Usare 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.