Share via

Azure Event Grid klientbibliotek för Python – version 4.16.0

  • Artikel

Azure Event Grid är en fullständigt hanterad smart händelsedirigeringstjänst för enhetlig händelsebearbetning med en offentlig prenumerationsmodell.

Källkod | Paket (PyPI) | Paket (Conda) | API-referensdokumentation | Produktdokumentation | Prover | Ändringsloggen

Komma igång

Förutsättningar

Installera paketet

Installera Azure Event Grid-klientbiblioteket för Python med pip:

pip install azure-eventgrid

Om du använder Azure CLI ersätter <resource-group-name> du och <resource-name> med dina egna unika namn.

Skapa ett Event Grid-ämne

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

Skapa en Event Grid-domän

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

Autentisera klienten

För att kunna interagera med Event Grid-tjänsten måste du skapa en instans av en klient. En slutpunkt och autentiseringsuppgifter krävs för att instansiera klientobjektet.

Använda Azure Active Directory (AAD)

Azure Event Grid tillhandahåller integrering med Azure Active Directory (Azure AD) för identitetsbaserad autentisering av begäranden. Med Azure AD kan du använda rollbaserad åtkomstkontroll (RBAC) för att ge åtkomst till dina Azure Event Grid resurser till användare, grupper eller program.

Om du vill skicka händelser till ett ämne eller en domän med en TokenCredentialska den autentiserade identiteten ha rollen "EventGrid Data Sender" tilldelad.

Med paketet azure-identity kan du smidigt auktorisera begäranden i både utvecklings- och produktionsmiljöer. Mer information om Azure Active Directory finns i azure-identity README.

Du kan till exempel använda DefaultAzureCredential för att skapa en klient som ska autentisera med Hjälp av 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)

Leta upp slutpunkten

Du hittar ämnesslutpunkten i Event Grid Topic-resursen på Azure Portal. Det här ser ut så här: "https://<event-grid-topic-name>.<topic-location>.eventgrid.azure.net/api/events"

Skapa klienten med AzureKeyCredential

Om du vill använda en åtkomstnyckel som credential parameter skickar du nyckeln som en sträng till en instans av AzureKeyCredential.

Observera: Åtkomstnyckeln finns på Azure-portalen på menyn "Åtkomstnycklar" i Event Grid-ämnesresursen. De kan också hämtas via azure CLI eller azure-mgmt-eventgrid biblioteket. En guide för att hämta åtkomstnycklar finns här.

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)

Observera: En klient kan också autentiseras via SAS-signatur med hjälp av AzureSasCredential. Ett exempel som visar detta finns här (async_version).

Observera: Metoden generate_sas kan användas för att generera en signatur för delad åtkomst. Ett exempel som visar detta visas här.

Viktiga begrepp

Avsnitt

Ett ämne är en kanal i EventGrid-tjänsten för att skicka händelser. Händelseschemat som ett ämne accepterar bestäms när ämnet skapas. Om händelser av en schematyp skickas till ett ämne som kräver en annan schematyp utlöses fel.

Domain

En händelsedomän är ett hanteringsverktyg för ett stort antal Event Grid-ämnen relaterade till samma program. De gör att du kan publicera händelser i tusentals ämnen. Domäner ger dig också auktorisering och autentiseringskontroll över varje ämne. Mer information finns i Översikt över händelsedomäner.

När du skapar en händelsedomän görs en publiceringsslutpunkt för den här domänen tillgänglig för dig. Den här processen liknar att skapa ett Event Grid-ämne. Den enda skillnaden är att när du publicerar till en domän måste du ange ämnet i domänen som du vill att händelsen ska levereras till.

Händelsescheman

En händelse är den minsta mängd information som helt beskriver något som hände i systemet. När ett anpassat ämne eller en domän skapas måste du ange det schema som ska användas vid publicering av händelser.

Event Grid stöder flera scheman för kodning av händelser.

Event Grid-schema

Du kan konfigurera ämnet så att det använder ett anpassat schema, men det är vanligare att använda det redan definierade Event Grid-schemat. Se specifikationerna och kraven här.

CloudEvents v1.0-schema

Ett annat alternativ är att använda CloudEvents v1.0-schemat. CloudEvents är ett Cloud Native Computing Foundation-projekt som skapar en specifikation för att beskriva händelsedata på ett vanligt sätt. Tjänstsammanfattningen för CloudEvents finns här.

EventGridPublisherClient

EventGridPublisherClient tillhandahåller åtgärder för att skicka händelsedata till ett ämnesvärdnamn som anges under klientinitieringen.

Oavsett vilket schema som ämnet eller domänen har konfigurerats att använda EventGridPublisherClient används för att publicera händelser till det. Använd metodpubliceringshändelserna send .

Följande format för händelser kan skickas:

  • En lista eller en enda instans av starkt skrivna EventGridEvents.

  • En diktamensrepresentation av ett serialiserat EventGridEvent-objekt.

  • En lista eller en enda instans av starkt skrivna CloudEvents.

  • En diktamensrepresentation av ett serialiserat CloudEvent-objekt.

  • En diktamensrepresentation av alla anpassade scheman.

Ta en titt på exemplen för detaljerade exempel.

Observera: Det är viktigt att veta om ditt ämne stöder CloudEvents eller EventGridEvents innan du publicerar. Om du skickar till ett ämne som inte stöder schemat för händelsen som du skickar utlöser send() ett undantag.

Systemämnen

Ett systemämne i Event Grid representerar en eller flera händelser som publicerats av Azure-tjänster som Azure Storage eller Azure Event Hubs. Ett systemämne kan till exempel representera alla blobhändelser eller endast händelser för skapande av blobar och borttagning av blobar som publicerats för ett specifikt lagringskonto.

Namnen på de olika händelsetyperna för de systemhändelser som publiceras till Azure Event Grid är tillgängliga i azure.eventgrid.SystemEventNames. En fullständig lista över identifierbara systemämnen finns i Systemämnen.

Mer information om viktiga begrepp i Event Grid finns i Begrepp i Azure Event Grid.

Event Grid på Kubernetes med Azure Arc

Event Grid på Kubernetes med Azure Arc är ett erbjudande som gör att du kan köra Event Grid på ditt eget Kubernetes-kluster. Den här funktionen aktiveras med hjälp av Azure Arc-aktiverade Kubernetes. Via Azure Arc-aktiverade Kubernetes ansluter ett Kubernetes-kluster som stöds till Azure. När du är ansluten kan du installera Event Grid på det. Läs mer om den här.

Stöd för CNCF-molnhändelser

Från och med v4.7.0 stöder det här paketet även publicering av en CNCF-molnhändelse från https://pypi.org/project/cloudevents/. Du skulle kunna skicka ett CloudEvent-objekt från det här biblioteket till API:et send .


from cloudevents.http import CloudEvent

event = CloudEvent(...)

client.send(event)

Exempel

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste Event Grid-uppgifterna, inklusive:

Skicka en Event Grid-händelse

Det här exemplet publicerar en Event Grid-händelse.

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)

Skicka en molnhändelse

I det här exemplet publiceras en molnhändelse.

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)

Skicka flera händelser

Det är möjligt att skicka händelser som en batch när du skickar flera händelser till ett ämne eller en domän. Det här exemplet skickar en lista över CloudEvents med hjälp av send-metoden.

VARNING: När du skickar en lista över flera händelser samtidigt resulterar iterering över och sändning av varje händelse inte i optimala prestanda. För bästa prestanda rekommenderar vi starkt att du skickar en lista över händelser.

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)

Skicka händelser som ordlistor

En dikteringsrepresentation av respektive serialiserade modeller kan också användas för att publicera CloudEvent(er) eller EventGridEvent(er) förutom de starkt typifierade objekten.

Använd en dict-liknande representation för att skicka till ett ämne med anpassat schema enligt nedan.

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)

Använda från lagringskö

Det här exemplet använder ett meddelande som tas emot från lagringskö och deserialiserar det till ett CloudEvent-objekt.

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]

Använda från servicebus

Det här exemplet använder ett nyttolastmeddelande som tas emot från ServiceBus och deserialiserar det till ett EventGridEvent-objekt.

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]

Distribuerad spårning med EventGrid

Du kan använda OpenTelemetry för Python som vanligt med EventGrid eftersom det är kompatibelt med azure-core-spårningsintegrering.

Här är ett exempel på hur du använder OpenTelemetry för att spåra sändning av en CloudEvent.

Ange först OpenTelemetry som aktiverat spårningsplugin för EventGrid.

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

settings.tracing_implementation = OpenTelemetrySpan

Regelbunden användning av öppen telemetri härifrån. Mer information finns i OpenTelemetry . I det här exemplet används en enkel konsolexportör för att exportera spårningarna. Alla exportörer kan användas här, inklusive azure-monitor-opentelemetry-exporter, jaegerosv zipkin .

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

tracer När och exporter har angetts följer du exemplet nedan för att börja samla in spårningar när du använder send metoden från EventGridPublisherClient för att skicka ett CloudEvent-objekt.

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)

Felsökning

  • Aktivera azure.eventgrid loggning för att samla in spårningar från biblioteket.

Allmänt

Event Grid-klientbiblioteket genererar undantag som definierats i Azure Core.

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Valfri konfiguration

Valfria nyckelordsargument kan skickas in på klient- och åtgärdsnivå. Referensdokumentationen för azure-core beskriver tillgängliga konfigurationer för återförsök, loggning, transportprotokoll med mera.

Nästa steg

Följande avsnitt innehåller flera kodfragment som illustrerar vanliga mönster som används i Event Grid Python-API:et.

Mer exempelkod

Dessa kodexempel visar vanliga champion-scenarioåtgärder med Azure Event Grid-klientbiblioteket.

Följande exempel beskriver publicering och användning dict av representationer av EventGridEvents och CloudEvents.

Fler exempel finns här.

  • Fler exempel som rör sändningsscenariot visas här.
  • Om du vill se fler exempel som rör användning av en nyttolast från olika meddelandetjänster som ett skrivet objekt kan du gå till Använda exempel

Ytterligare dokumentation

Mer omfattande dokumentation om Azure Event Grid finns i Event Grid-dokumentationen på docs.microsoft.com.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns i cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.