Delen via

Azure Event Grid clientbibliotheek voor Python - versie 4.16.0

  • Artikel

Azure Event Grid is een volledig beheerde, intelligente service voor gebeurtenisroutering die uniform gebeurtenisverbruik mogelijk maakt op basis van een Publish-Subscribe-model.

Broncode | Pakket (PyPI) | Pakket (Conda) | API-referentiedocumentatie | Productdocumentatie | Monsters | Changelog

Aan de slag

Vereisten

Het pakket installeren

Installeer de Azure Event Grid-clientbibliotheek voor Python met pip:

pip install azure-eventgrid
  • Er is een bestaand Event Grid-onderwerp of -domein vereist. U kunt de resource maken met behulp van Azure Portal of Azure CLI

Als u Azure CLI gebruikt, vervangt u en <resource-name> door <resource-group-name> uw eigen unieke namen.

Een Event Grid-onderwerp maken

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

Een Event Grid-domein maken

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

De client verifiëren

Als u wilt communiceren met de Event Grid-service, moet u een exemplaar van een client maken. Er zijn een eindpunt en referenties nodig om het clientobject te instantiëren.

Azure Active Directory (AAD) gebruiken

Azure Event Grid biedt integratie met Azure Active Directory (Azure AD) voor identiteitsverificatie van aanvragen. Met Azure AD kunt u op rollen gebaseerd toegangsbeheer (RBAC) gebruiken om gebruikers, groepen of toepassingen toegang te verlenen tot uw Azure Event Grid-resources.

Als u gebeurtenissen wilt verzenden naar een onderwerp of domein met een TokenCredential, moet aan de geverifieerde identiteit de rol 'EventGrid-gegevensverzender' zijn toegewezen.

Met het azure-identity pakket kunt u naadloos aanvragen autoriseren in zowel ontwikkel- als productieomgevingen. Zie leesmijazure-identity voor meer informatie over Azure Active Directory.

U kunt bijvoorbeeld gebruiken DefaultAzureCredential om een client te maken die wordt geverifieerd met behulp van 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)

Het eindpunt opzoeken

U vindt het onderwerpeindpunt in de Event Grid-onderwerpresource op de Azure Portal. Dit ziet er als volgt uit: "https://<event-grid-topic-name>.<topic-location>.eventgrid.azure.net/api/events"

De client maken met AzureKeyCredential

Als u een toegangssleutel als parameter credential wilt gebruiken, geeft u de sleutel door als een tekenreeks aan een exemplaar van AzureKeyCredential.

Opmerking: U vindt de toegangssleutel in azure Portal in het menu Toegangssleutels van de Event Grid-onderwerpresource. Ze kunnen ook worden verkregen via de Azure CLI of de azure-mgmt-eventgrid bibliotheek. Hier vindt u een handleiding voor het ophalen van toegangssleutels.

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)

Opmerking: Een client kan ook worden geverifieerd via een SAS-handtekening, met behulp van de AzureSasCredential. Hier (async_version) vindt u een voorbeeld dat dit aantoont.

Opmerking: De generate_sas methode kan worden gebruikt om een shared access signature te genereren. Hier ziet u een voorbeeld dat dit aantoont.

Belangrijkste concepten

Onderwerp

Een onderwerp is een kanaal binnen de EventGrid-service om gebeurtenissen te verzenden. Het gebeurtenisschema dat een onderwerp accepteert, wordt bepaald tijdens het maken van het onderwerp. Als gebeurtenissen van een schematype worden verzonden naar een onderwerp waarvoor een ander schematype is vereist, worden er fouten gegenereerd.

Domain

Een gebeurtenisdomein is een beheerprogramma voor grote aantallen Event Grid-onderwerpen met betrekking tot dezelfde toepassing. Hiermee kunt u gebeurtenissen publiceren naar duizenden onderwerpen. Domeinen bieden u ook autorisatie- en verificatiebeheer voor elk onderwerp. Ga naar Overzicht van gebeurtenisdomein voor meer informatie.

Wanneer u een gebeurtenisdomein maakt, wordt een publicatie-eindpunt voor dit domein voor u beschikbaar gesteld. Dit proces is vergelijkbaar met het maken van een Event Grid-onderwerp. Het enige verschil is dat u bij het publiceren naar een domein het onderwerp moet opgeven in het domein waarnaar u de gebeurtenis wilt laten bezorgen.

Gebeurtenisschema's

Een gebeurtenis is de kleinste hoeveelheid informatie die een volledige beschrijving geeft van iets dat in het systeem is gebeurd. Wanneer een aangepast onderwerp of domein wordt gemaakt, moet u het schema opgeven dat wordt gebruikt bij het publiceren van gebeurtenissen.

Event Grid ondersteunt meerdere schema's voor het coderen van gebeurtenissen.

Event Grid-schema

Hoewel u uw onderwerp kunt configureren voor het gebruik van een aangepast schema, is het gebruikelijker om het al gedefinieerde Event Grid-schema te gebruiken. Bekijk hier de specificaties en vereisten.

CloudEvents v1.0-schema

Een andere optie is het cloudEvents v1.0-schema te gebruiken. CloudEvents is een Cloud Native Computing Foundation-project dat een specificatie produceert voor het beschrijven van gebeurtenisgegevens op een algemene manier. Het serviceoverzicht van CloudEvents vindt u hier.

EventGridPublisherClient

EventGridPublisherClient biedt bewerkingen voor het verzenden van gebeurtenisgegevens naar een onderwerphostnaam die is opgegeven tijdens de initialisatie van de client.

Ongeacht het schema dat uw onderwerp of domein is geconfigureerd voor gebruik, EventGridPublisherClient wordt gebruikt om gebeurtenissen naar het onderwerp of domein te publiceren. Gebruik de send methode voor het publiceren van gebeurtenissen.

De volgende indelingen van gebeurtenissen mogen worden verzonden:

  • Een lijst of één exemplaar van sterk getypte EventGridEvents.

  • Een dictweergave van een geserialiseerd EventGridEvent-object.

  • Een lijst of één exemplaar van sterk getypte CloudEvents.

  • Een dictweergave van een geserialiseerd CloudEvent-object.

  • Een dictweergave van een aangepast schema.

Bekijk de voorbeelden voor gedetailleerde voorbeelden.

Opmerking: Het is belangrijk om te weten of uw onderwerp CloudEvents of EventGridEvents ondersteunt voordat u deze publiceert. Als u verzendt naar een onderwerp dat geen ondersteuning biedt voor het schema van de gebeurtenis die u verzendt, genereert send() een uitzondering.

Systeemonderwerpen

Een systeemonderwerp in Event Grid vertegenwoordigt een of meer gebeurtenissen die zijn gepubliceerd door Azure-services zoals Azure Storage of Azure Event Hubs. Een systeemonderwerp kan bijvoorbeeld alle blob-gebeurtenissen vertegenwoordigen of alleen gebeurtenissen voor het maken en verwijderen van blobs die zijn gepubliceerd voor een specifiek opslagaccount.

De namen van de verschillende gebeurtenistypen voor de systeemevenementen die zijn gepubliceerd naar Azure Event Grid zijn beschikbaar in azure.eventgrid.SystemEventNames. Ga naar Systeemonderwerpen voor een volledige lijst met herkenbare systeemonderwerpen.

Zie Concepten in Azure Event Grid voor meer informatie over de belangrijkste concepten in Event Grid.

Event Grid in Kubernetes met Azure Arc

Event Grid in Kubernetes met Azure Arc is een aanbieding waarmee u Event Grid kunt uitvoeren op uw eigen Kubernetes-cluster. Deze mogelijkheid wordt ingeschakeld door het gebruik van Kubernetes met Azure Arc. Via Kubernetes met Azure Arc maakt een ondersteund Kubernetes-cluster verbinding met Azure. Zodra u verbinding hebt gemaakt, kunt u Event Grid erop installeren. Hier vindt u meer informatie.

Ondersteuning voor CNCF-cloudevenementen

Vanaf v4.7.0 ondersteunt dit pakket ook het publiceren van een CNCF-cloudevenement van https://pypi.org/project/cloudevents/. U kunt dan een CloudEvent-object uit deze bibliotheek doorgeven aan de send API.


from cloudevents.http import CloudEvent

event = CloudEvent(...)

client.send(event)

Voorbeelden

De volgende secties bevatten verschillende codefragmenten voor enkele van de meest voorkomende Event Grid-taken, waaronder:

Een Event Grid-gebeurtenis verzenden

In dit voorbeeld wordt een Event Grid-gebeurtenis gepubliceerd.

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)

Een cloud-gebeurtenis verzenden

In dit voorbeeld wordt een Cloud-gebeurtenis gepubliceerd.

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)

Meerdere gebeurtenissen verzenden

Het is mogelijk om gebeurtenissen als batch te verzenden bij het verzenden van meerdere gebeurtenissen naar een onderwerp of een domein. In dit voorbeeld wordt een lijst met CloudEvents verzonden met behulp van de methode send.

WAARSCHUWING: Wanneer u een lijst met meerdere gebeurtenissen tegelijk verzendt, resulteert het herhalen en verzenden van elke gebeurtenis niet in optimale prestaties. Voor de beste prestaties wordt het ten zeerste aanbevolen om een lijst met gebeurtenissen te verzenden.

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)

Gebeurtenissen verzenden als woordenlijsten

Een dict-weergave van de respectieve geserialiseerde modellen kan ook worden gebruikt om CloudEvent(s) of EventGridEvent(s) te publiceren, afgezien van de sterk getypte objecten.

Gebruik een dicteerachtige weergave om naar een onderwerp te verzenden met een aangepast schema, zoals hieronder wordt weergegeven.

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)

Verbruiken vanuit opslagwachtrij

In dit voorbeeld wordt een bericht gebruikt dat is ontvangen van de opslagwachtrij en wordt dit gedeserialiseerd naar een CloudEvent-object.

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]

Verbruiken vanuit servicebus

In dit voorbeeld wordt een nettoladingbericht gebruikt dat is ontvangen van ServiceBus en wordt dit gedeserialiseerd naar een EventGridEvent-object.

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]

Gedistribueerde tracering met EventGrid

U kunt OpenTelemetry voor Python gebruiken zoals gebruikelijk met EventGrid, omdat het compatibel is met azure-core-traceringsintegratie.

Hier volgt een voorbeeld van het gebruik van OpenTelemetry om het verzenden van een CloudEvent te traceren.

Stel eerst OpenTelemetry in als ingeschakelde invoegtoepassing voor tracering voor EventGrid.

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

settings.tracing_implementation = OpenTelemetrySpan

Regelmatig open telemetriegebruik vanaf hier. Zie OpenTelemetry voor meer informatie. In dit voorbeeld wordt een eenvoudige consoleexporteur gebruikt om de traceringen te exporteren. Elke exporteur kan hier worden gebruikt, met inbegrip azure-monitor-opentelemetry-exportervan , jaeger, zipkin enz.

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

Zodra de tracer en exporter zijn ingesteld, volgt u het onderstaande voorbeeld om traceringen te verzamelen terwijl u de send methode van de EventGridPublisherClient gebruikt om een CloudEvent-object te verzenden.

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)

Problemen oplossen

  • Logboekregistratie inschakelen azure.eventgrid om traceringen uit de bibliotheek te verzamelen.

Algemeen

Event Grid-clientbibliotheek genereert uitzonderingen die zijn gedefinieerd in Azure Core.

Logboekregistratie

Deze bibliotheek gebruikt de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO-niveau.

Optionele configuratie

Optionele trefwoordargumenten kunnen worden doorgegeven op het niveau van de client en per bewerking. In de referentiedocumentatie voor Azure Core worden de beschikbare configuraties beschreven voor nieuwe pogingen, logboekregistratie, transportprotocollen en meer.

Volgende stappen

De volgende sectie bevat verschillende codefragmenten die veelvoorkomende patronen illustreren die worden gebruikt in de Event Grid Python-API.

Meer voorbeeldcode

Deze codevoorbeelden tonen veelvoorkomende scenariobewerkingen met de Azure Event Grid clientbibliotheek.

De volgende voorbeelden hebben betrekking op het publiceren en gebruiken dict van weergaven van EventGridEvents en CloudEvents.

Meer voorbeelden vindt u hier.

  • Meer voorbeelden met betrekking tot het verzendscenario vindt u hier.
  • Als u meer voorbeelden wilt zien met betrekking tot het gebruik van een nettolading van verschillende berichtenservices als een getypt object, gaat u naar Voorbeelden gebruiken

Aanvullende documentatie

Zie de Event Grid-documentatie over docs.microsoft.com voor uitgebreidere documentatie over Azure Event Grid.

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.