Azure Event Grid Clientbibliothek für Python– Version 4.16.0

  • Artikel

Azure Event Grid ist ein vollständig verwalteter intelligenter Dienst für das Ereignisrouting, der eine einheitliche Ereignisnutzung mithilfe eines Veröffentlichen/Abonnieren-Modells ermöglicht.

Quellcode | Paket (PyPI) | Paket (Conda) | API-Referenzdokumentation | Produktdokumentation | Proben | Changelog

Erste Schritte

Voraussetzungen

Installieren des Pakets

Installieren Sie die Azure Event Grid-Clientbibliothek für Python mit pip:

pip install azure-eventgrid
  • Ein vorhandenes Event Grid-Thema oder eine vorhandene Domäne ist erforderlich. Sie können die Ressource über das Azure-Portal oder die Azure CLI erstellen.

Wenn Sie die Azure CLI verwenden, ersetzen <resource-group-name> Sie und <resource-name> durch Ihre eigenen eindeutigen Namen.

Erstellen eines Event Grid-Themas

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

Erstellen einer Event Grid-Domäne

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

Authentifizieren des Clients

Um mit dem Event Grid-Dienst zu interagieren, müssen Sie eine instance eines Clients erstellen. Ein Endpunkt und Anmeldeinformationen sind erforderlich, um das Clientobjekt zu instanziieren.

Verwenden von Azure Active Directory (AAD)

Azure Event Grid ermöglicht die Integration in Azure Active Directory (Azure AD) für die identitätsbasierte Authentifizierung von Anforderungen. Mit Azure AD können Sie die rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) verwenden, um Benutzern, Gruppen oder Anwendungen Zugriff auf Ihre Azure Event Grid-Ressourcen zu gewähren.

Um Ereignisse mit einem an ein Thema oder eine TokenCredentialDomäne zu senden, muss der authentifizierten Identität die Rolle "EventGrid-Datensender" zugewiesen sein.

Mit dem azure-identity Paket können Sie Anforderungen nahtlos in Entwicklungs- und Produktionsumgebungen autorisieren. Weitere Informationen zu Azure Active Directory finden Sie in der azure-identity Infodatei.

Sie können beispielsweise verwenden DefaultAzureCredential , um einen Client zu erstellen, der sich mithilfe von Azure Active Directory authentifiziert:

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)

Nachschlagen des Endpunkts

Sie finden den Themenendpunkt in der Event Grid Topic-Ressource auf der Azure-Portal. Dies sieht wie folgt aus: "https://<event-grid-topic-name>.<topic-location>.eventgrid.azure.net/api/events"

Erstellen des Clients mit AzureKeyCredential

Um einen Access-Schlüssel als credential Parameter zu verwenden, übergeben Sie den Schlüssel als Zeichenfolge an eine instance von AzureKeyCredential.

Hinweis: Der Zugriffsschlüssel befindet sich im Azure-Portal im Menü "Zugriffsschlüssel" der Event Grid-Themenressource. Sie können auch über die Azure CLI oder die azure-mgmt-eventgrid Bibliothek abgerufen werden. Eine Anleitung zum Abrufen von Zugriffsschlüsseln finden Sie hier.

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)

Hinweis: Ein Client kann auch mithilfe der AzureSasCredentialSAS-Signatur authentifiziert werden. Ein Beispiel, das dies veranschaulicht, finden Sie hier (async_version).

Hinweis: Die generate_sas -Methode kann verwendet werden, um eine Shared Access Signature zu generieren. Ein Beispiel, das dies veranschaulicht, finden Sie hier.

Wichtige Begriffe

Thema

Ein Thema ist ein Kanal innerhalb des EventGrid-Diensts zum Senden von Ereignissen. Das Ereignisschema, das ein Thema akzeptiert, wird bei der Erstellung des Themas festgelegt. Wenn Ereignisse eines Schematyps an ein Thema gesendet werden, das einen anderen Schematyp erfordert, werden Fehler ausgelöst.

Domain

Eine Ereignisdomäne ist ein Verwaltungstool für eine große Anzahl von Event Grid-Themen im Zusammenhang mit derselben Anwendung. Sie ermöglichen es Ihnen, Ereignisse für Tausende von Themen zu veröffentlichen. Domänen ermöglichen Ihnen auch die Autorisierungs- und Authentifizierungssteuerung für jedes Thema. Weitere Informationen finden Sie unter Übersicht über die Ereignisdomäne.

Wenn Sie eine Ereignisdomäne erstellen, wird Ihnen ein Veröffentlichungsendpunkt für diese Domäne zur Verfügung gestellt. Dieser Vorgang ähnelt dem Erstellen eines Event Grid-Themas. Der einzige Unterschied besteht darin, dass Sie beim Veröffentlichen in einer Domäne das Thema innerhalb der Domäne angeben müssen, an die das Ereignis übermittelt werden soll.

Ereignisschemas

Ein Ereignis ist die kleinste Menge an Informationen, die etwas, das im System passiert ist, vollständig beschreibt. Wenn ein benutzerdefiniertes Thema oder eine benutzerdefinierte Domäne erstellt wird, müssen Sie das Schema angeben, das beim Veröffentlichen von Ereignissen verwendet wird.

Event Grid unterstützt mehrere Schemas für die Codierung von Ereignissen.

Event Grid-Schema

Sie können Ihr Thema zwar für die Verwendung eines benutzerdefinierten Schemas konfigurieren, es ist jedoch üblicher, das bereits definierte Event Grid-Schema zu verwenden. Sehen Sie sich die Spezifikationen und Anforderungen hier an.

CloudEvents v1.0-Schema

Eine weitere Möglichkeit besteht darin, das CloudEvents v1.0-Schema zu verwenden. CloudEvents ist ein Cloud Native Computing Foundation-Projekt, das eine Spezifikation für die allgemeine Beschreibung von Ereignisdaten erstellt. Die Dienstzusammenfassung von CloudEvents finden Sie hier.

EventGridPublisherClient

EventGridPublisherClient stellt Vorgänge zum Senden von Ereignisdaten an einen Themenhostnamen bereit, der während der Clientinitialisierung angegeben wurde.

Unabhängig vom Schema, für das Ihr Thema oder Ihre Domäne konfiguriert ist, EventGridPublisherClient wird zum Veröffentlichen von Ereignissen verwendet. Verwenden Sie die send -Methode zum Veröffentlichen von Ereignissen.

Die folgenden Formate von Ereignissen können gesendet werden:

  • Eine Liste oder eine einzelne instance von stark typisierten EventGridEvents.

  • Eine Diktatdarstellung eines serialisierten EventGridEvent-Objekts.

  • Eine Liste oder eine einzelne instance von stark typisierten CloudEvents.

  • Eine Diktatdarstellung eines serialisierten CloudEvent-Objekts.

  • Eine Diktatdarstellung eines beliebigen benutzerdefinierten Schemas.

Ausführliche Beispiele finden Sie in den Beispielen .

Hinweis: Es ist wichtig zu wissen, ob Ihr Thema CloudEvents oder EventGridEvents vor der Veröffentlichung unterstützt. Wenn Sie an ein Thema senden, das das Schema des von Ihnen gesendeten Ereignisses nicht unterstützt, löst send() eine Ausnahme aus.

Systemthemen

Ein Systemthema in Event Grid stellt mindestens ein Ereignis dar, das von Azure-Diensten wie Azure Storage oder Azure Event Hubs veröffentlicht wird. Beispielsweise kann ein Systemthema alle Blobereignisse oder nur Bloberstellungs- und Bloblöschereignisse darstellen, die für ein bestimmtes Speicherkonto veröffentlicht wurden.

Die Namen der verschiedenen Ereignistypen für die in Azure Event Grid veröffentlichten Systemereignisse sind in azure.eventgrid.SystemEventNamesverfügbar. Eine vollständige Liste der erkennbaren Systemthemen finden Sie unter Systemthemen.

Weitere Informationen zu den wichtigsten Konzepten in Event Grid finden Sie unter Konzepte in Azure Event Grid.

Event Grid in Kubernetes mit Azure Arc

Bei Event Grid in Kubernetes mit Azure Arc handelt es sich um ein Angebot, mit dem Sie Event Grid in Ihrem eigenen Kubernetes-Cluster ausführen können. Diese Funktion wird durch die Verwendung von Azure Arc-fähigen Kubernetes aktiviert. Ein unterstützter Kubernetes-Cluster wird über Azure Arc-fähige Kubernetes mit Azure verbunden. Sobald die Verbindung besteht, können Sie Event Grid installieren. Weitere Informationen dazu finden Sie hier.

Unterstützung für CNCF-Cloudereignisse

Ab v4.7.0 unterstützt dieses Paket auch die Veröffentlichung eines CNCF-Cloudereignisses aus https://pypi.org/project/cloudevents/. Sie könnten ein CloudEvent-Objekt aus dieser Bibliothek an die send API übergeben.


from cloudevents.http import CloudEvent

event = CloudEvent(...)

client.send(event)

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der gängigsten Event Grid-Aufgaben abdecken, einschließlich:

Senden eines Event Grid-Ereignisses

In diesem Beispiel wird ein Event Grid-Ereignis veröffentlicht.

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)

Senden eines Cloudereignisses

In diesem Beispiel wird ein Cloudereignis veröffentlicht.

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)

Senden mehrerer Ereignisse

Es ist möglich, Ereignisse als Batch zu senden, wenn mehrere Ereignisse an ein Thema oder eine Domäne gesendet werden. In diesem Beispiel wird eine Liste von CloudEvents mithilfe der send-Methode gesendet.

WARNUNG: Wenn Sie eine Liste mehrerer Ereignisse gleichzeitig senden, führt das Durchlaufen und Senden jedes Ereignisses nicht zu einer optimalen Leistung. Für eine optimale Leistung wird dringend empfohlen, eine Liste von Ereignissen zu senden.

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)

Senden von Ereignissen als Wörterbücher

Eine Diktatdarstellung der jeweiligen serialisierten Modelle kann auch verwendet werden, um CloudEvent(s) oder EventGridEvent(s) außer den stark typisierten Objekten zu veröffentlichen.

Verwenden Sie eine diktierähnliche Darstellung, um an ein Thema mit benutzerdefiniertem Schema zu senden, wie unten gezeigt.

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)

Nutzen aus Der Speicherwarteschlange

In diesem Beispiel wird eine von der Speicherwarteschlange empfangene Nachricht verwendet und in ein CloudEvent-Objekt deserialisiert.

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]

Nutzen von Servicebus

In diesem Beispiel wird eine von ServiceBus empfangene Nutzlastnachricht verwendet und in ein EventGridEvent-Objekt deserialisiert.

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]

Verteilte Ablaufverfolgung mit EventGrid

Sie können OpenTelemetry für Python wie gewohnt mit EventGrid verwenden, da es mit der Integration der Azure Core-Ablaufverfolgung kompatibel ist.

Hier sehen Sie ein Beispiel für die Verwendung von OpenTelemetry zum Nachverfolgen des Sendens eines CloudEvents.

Legen Sie zunächst OpenTelemetry als aktiviertes Ablaufverfolgungs-Plug-In für EventGrid fest.

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

settings.tracing_implementation = OpenTelemetrySpan

Von hier aus werden regelmäßig geöffnete Telemetriedaten verwendet. Weitere Informationen finden Sie unter OpenTelemetry . In diesem Beispiel wird ein einfacher Konsolenexportierer verwendet, um die Ablaufverfolgungen zu exportieren. Hier kann ein beliebiger Exporter verwendet werden, einschließlich azure-monitor-opentelemetry-exporter, jaegerusw 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)
)

Nachdem und tracerexporter festgelegt wurden, folgen Sie dem folgenden Beispiel, um mit dem Sammeln von Ablaufverfolgungen zu beginnen, während Sie die send -Methode von verwenden, EventGridPublisherClient um ein CloudEvent-Objekt zu senden.

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)

Problembehandlung

  • Aktivieren Sie azure.eventgrid die Protokollierung, um Ablaufverfolgungen aus der Bibliothek zu sammeln.

Allgemein

Die Event Grid-Clientbibliothek löst ausnahmen aus, die in Azure Core definiert sind.

Protokollierung

Diese Bibliothek verwendet die Standardprotokollbibliothek für die Protokollierung. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.

Optionale Konfiguration

Optionale Schlüsselwort (keyword) Argumente können auf Client- und Vorgangsebene übergeben werden. In der Azure Core-Referenzdokumentation werden verfügbare Konfigurationen für Wiederholungen, Protokollierung, Transportprotokolle und vieles mehr beschrieben.

Nächste Schritte

Der folgende Abschnitt enthält mehrere Codeausschnitte, die gängige Muster veranschaulichen, die in der Event Grid-Python-API verwendet werden.

Weiterer Beispielcode

Diese Codebeispiele zeigen allgemeine Champion-Szenariovorgänge mit der Azure Event Grid-Clientbibliothek.

Die folgenden Beispiele behandeln das Veröffentlichen und Nutzen dict von Darstellungen von EventGridEvents und CloudEvents.

Weitere Beispiele finden Sie hier.

  • Weitere Beispiele im Zusammenhang mit dem Sendeszenario finden Sie hier.
  • Weitere Beispiele zur Nutzung einer Nutzlast von verschiedenen Messagingdiensten als typisiertes Objekt finden Sie unter Nutzen von Beispielen.

Zusätzliche Dokumentation

Eine ausführlichere Dokumentation zu Azure Event Grid finden Sie in der Event Grid-Dokumentation auf docs.microsoft.com.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.