Share via

Azure Event Grid Python ügyfélkódtára – 4.16.0-s verzió

  • Cikk

A teljeskörűen felügyelt Azure Event Grid intelligens esemény-útválasztó szolgáltatás közzétételi-feliratkozási modell alkalmazásával teszi lehetővé az egységesített eseményfelhasználást.

Forráskód | Csomag (PyPI) | Csomag (Conda) | API-referenciadokumentáció | Termékdokumentáció | Minták | Változatlan

Első lépések

Előfeltételek

A csomag telepítése

Telepítse a Pythonhoz készült Azure Event Grid ügyfélkódtárat a pip használatával:

pip install azure-eventgrid
  • Szükség van egy meglévő Event Grid-témakörre vagy -tartományra. Az erőforrást az Azure Portal vagy az Azure CLI használatával hozhatja létre

Ha az Azure CLI-t használja, cserélje le <resource-group-name> a és <resource-name> a nevet a saját egyedi nevére.

Event Grid-témakör létrehozása

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

Event Grid-tartomány létrehozása

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

Az ügyfél hitelesítése

Az Event Grid szolgáltatás használatához létre kell hoznia egy ügyfélpéldányt. Az ügyfélobjektum példányosításához végpontra és hitelesítő adatokra van szükség.

Az Azure Active Directory (AAD) használata

Azure Event Grid integrációt biztosít az Azure Active Directoryval (Azure AD) a kérések identitásalapú hitelesítéséhez. A Azure AD szerepköralapú hozzáférés-vezérléssel (RBAC) biztosíthat hozzáférést a Azure Event Grid-erőforrásokhoz felhasználók, csoportok vagy alkalmazások számára.

Ha eseményeket szeretne küldeni egy témakörbe vagy tartományba egy TokenCredentialhasználatával, a hitelesített identitáshoz hozzá kell rendelni az "EventGrid Data Sender" szerepkört.

A csomaggal zökkenőmentesen engedélyezheti a azure-identity kéréseket fejlesztési és éles környezetben is. További információ az Azure Active Directoryról: azure-identity README.

A használatával DefaultAzureCredential például létrehozhat egy ügyfelet, amely az Azure Active Directoryval fog hitelesíteni:

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)

A végpont keresése

A témakörvégpontot az Event Grid-témakör erőforrásban találja a Azure Portal. Ez a következőképpen fog kinézni: "https://<event-grid-topic-name>.<topic-location>.eventgrid.azure.net/api/events"

Az ügyfél létrehozása az AzureKeyCredential használatával

Az Access-kulcs paraméterként credential való használatához adja át a kulcsot sztringként az AzureKeyCredential egy példányába.

Megjegyzés: A hozzáférési kulcs az Azure Portal Event Grid-témakör erőforrásának "Hozzáférési kulcsok" menüjében található. Ezek az azure CLI-vel vagy a kódtáron azure-mgmt-eventgrid keresztül is beszerezhetők. A hozzáférési kulcsok lekérésére vonatkozó útmutatót itt találja.

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)

Megjegyzés: Az ügyfél sas-aláírással is hitelesíthető a AzureSasCredentialhasználatával. Ezt bemutató minta itt érhető el (async_version).

Megjegyzés: A generate_sas metódus használható közös hozzáférésű jogosultságkód létrehozásához. Ezt bemutató minta itt tekinthető meg.

Fő fogalmak

Témakör

A témakör az EventGrid szolgáltatás csatornája, amely eseményeket küld. A témakör által elfogadott eseményséma a témakör létrehozásakor lesz eldöntve. Ha egy sématípus eseményeit egy másik sématípust igénylő témakörnek küldi el a rendszer, hibák keletkeznek.

Tartomány

Az eseménytartomány egy olyan felügyeleti eszköz, amely számos, az adott alkalmazáshoz kapcsolódó Event Grid-témakört tartalmaz. Lehetővé teszik, hogy eseményeket tegyen közzé több ezer témakörben. A tartományok emellett engedélyezési és hitelesítési vezérlést is biztosítanak az egyes témakörök felett. További információt az Eseménytartomány áttekintése című témakörben talál.

Eseménytartomány létrehozásakor a tartomány közzétételi végpontja elérhetővé válik. Ez a folyamat hasonló az Event Grid-témakör létrehozásához. Az egyetlen különbség az, hogy amikor közzétesz egy tartományt, meg kell adnia azt a témakört azon a tartományon belül, amelybe az eseményt el szeretné juttatni.

Eseménysémák

Az esemény a legkisebb mennyiségű információ, amely teljes mértékben leírja, hogy mi történt a rendszerben. Egyéni témakör vagy tartomány létrehozásakor meg kell adnia az események közzétételekor használni kívánt sémát.

Az Event Grid több sémát támogat az események kódolásához.

Event Grid-séma

Bár a témakört egyéni séma használatára is konfigurálhatja, a már definiált Event Grid-séma használata gyakoribb. A specifikációkat és követelményeket itt tekinti meg.

CloudEvents v1.0 séma

Egy másik lehetőség a CloudEvents v1.0 séma használata. A CloudEvents egy Cloud Native Computing Foundation-projekt, amely egy specifikációt állít elő az eseményadatok közös leírásához. A CloudEvents szolgáltatás összefoglalása itt található.

EventGridPublisherClient

EventGridPublisherClient műveleteket biztosít az eseményadatoknak az ügyfél inicializálása során megadott témakörgazdanévre való küldéséhez.

Függetlenül attól, hogy a témakör vagy tartomány milyen sémát használ, EventGridPublisherClient a rendszer események közzétételére fogja használni. Használja az események közzétételi send metódusát.

Az alábbi eseményformátumok küldhetők el:

  • Egy lista vagy egy példány erősen beírt EventGridEventsből.

  • Egy szerializált EventGridEvent objektum diktált ábrázolása.

  • Egy lista vagy egy példány erősen beírt CloudEventsből.

  • Egy szerializált CloudEvent-objektum diktált ábrázolása.

  • Bármely egyéni séma diktálási ábrázolása.

Részletes példákért tekintse meg a mintákat .

Megjegyzés: Fontos tudni, hogy a témakör támogatja-e a CloudEvents vagy az EventGridEvents használatát a közzététel előtt. Ha olyan témakörbe küld, amely nem támogatja a küldendő esemény sémáját, a send() kivételt jelez.

Rendszertémakörök

Az Event Grid rendszertémaköre egy vagy több, az Azure-szolgáltatások, például az Azure Storage vagy Azure Event Hubs által közzétett eseményt jelöl. Egy rendszertémakör például az összes blobeseményt, vagy csak egy adott tárfiókban közzétett bloblétrehozás és blobtörlési eseményeket jelölheti.

A Azure Event Grid közzétett rendszeresemények különböző eseménytípusainak nevei a következő helyen érhetők el: azure.eventgrid.SystemEventNames. A felismerhető rendszertémakörök teljes listáját a Rendszertémakörök című témakörben találja.

Az Event Grid fő fogalmaival kapcsolatos további információkért lásd: A Azure Event Grid alapfogalmai.

Event Grid a Kubernetesen az Azure Arc használatával

Az Event Grid a Kubernetesen és az Azure Arcon egy olyan ajánlat, amely lehetővé teszi az Event Grid futtatását a saját Kubernetes-fürtön. Ezt a képességet az Azure Arc-kompatibilis Kubernetes használata teszi lehetővé. Az Azure Arc-kompatibilis Kubernetesen keresztül egy támogatott Kubernetes-fürt csatlakozik az Azure-hoz. A csatlakozás után telepítheti az Event Gridet. További információt itt találhat.

CNCF-felhőesemények támogatása

A 4.7.0-s verziótól kezdődően ez a csomag támogatja a CNCF felhőesemények közzétételét is a-ből https://pypi.org/project/cloudevents/. Ebből a kódtárból át tud adni egy CloudEvent objektumot az send API-nak.


from cloudevents.http import CloudEvent

event = CloudEvent(...)

client.send(event)

Példák

A következő szakaszok számos kódrészletet biztosítanak, amelyek a leggyakoribb Event Grid-feladatokat fedik le, többek között:

Event Grid-esemény küldése

Ez a példa egy Event Grid-eseményt tesz közzé.

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)

Felhőbeli esemény küldése

Ez a példa egy felhőeseményt tesz közzé.

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)

Több esemény küldése

Az események kötegként is elküldhetők, ha több eseményt küldenek egy témakörbe vagy tartományba. Ez a példa a CloudEvents listáját küldi el a send metódussal.

FIGYELMEZTETÉS: Ha egyszerre több esemény listáját küldi el, az egyes események iterálása és elküldése nem eredményezi az optimális teljesítményt. A legjobb teljesítmény érdekében erősen ajánlott eseménylistát küldeni.

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)

Események küldése szótárként

A megfelelő szerializált modellek diktált ábrázolása is használható CloudEvent(ek) vagy EventGridEvent(ek) közzétételére az erősen beírt objektumokon kívül.

A diktálásszerű ábrázolás használatával egyéni sémát tartalmazó témakörbe küldheti azokat az alább látható módon.

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)

Felhasználás a tárolási üzenetsorból

Ez a példa felhasználja a tárolási üzenetsorból kapott üzenetet, és deszerializálja azt egy CloudEvent-objektumba.

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]

Felhasználás a servicebusból

Ez a példa a ServiceBustól kapott hasznos adatüzenetet használja fel, és deszerializálja azt egy EventGridEvent objektumba.

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]

Elosztott nyomkövetés az EventGriddel

Az OpenTelemetry for Pythont a szokásos módon használhatja az EventGriddel, mivel kompatibilis az Azure-core nyomkövetési integrációval.

Íme egy példa a CloudEvent küldésének nyomon követésére az OpenTelemetry használatával.

Először állítsa be az OpenTelemetryt engedélyezett nyomkövetési beépülő modulként az EventGridhez.

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

settings.tracing_implementation = OpenTelemetrySpan

Innen rendszeres nyitott telemetriai használat. A részletekért lásd: OpenTelemetry . Ez a példa egy egyszerű konzolexportáló használatával exportálja a nyomkövetéseket. Itt bármely exportőr használható, beleértve a azure-monitor-opentelemetry-exporter, jaegerstb 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 A és exporter beállítását követően kövesse az alábbi példát, hogy megkezdje a nyomkövetések gyűjtését, miközben a metódust használja a sendEventGridPublisherClient metódussal egy CloudEvent-objektum elküldéséhez.

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)

Hibaelhárítás

  • Engedélyezze azure.eventgrid a naplózónak, hogy nyomkövetéseket gyűjtsön a kódtárból.

Általános kérdések

Az Event Grid-ügyfélkódtár kivételeket hoz létre az Azure Core-ban.

Naplózás

Ez a kódtár a szabványos naplózási kódtárat használja a naplózáshoz. A HTTP-munkamenetekkel (URL-címekkel, fejlécekkel stb.) kapcsolatos alapvető információkat az INFO szinten naplózza a rendszer.

Választható konfiguráció

Az opcionális kulcsszóargumentumok az ügyfél és a művelet szintjén is átadhatók. Az Azure-Core referenciadokumentációja többek között az újrapróbálkozásokhoz, a naplózáshoz, az átviteli protokollokhoz és egyebekhez elérhető konfigurációkat ismerteti.

Következő lépések

A következő szakasz számos kódrészletet tartalmaz, amely az Event Grid Python API-ban használt gyakori mintákat szemlélteti.

További mintakód

Ezek a kódminták a Azure Event Grid ügyfélkódtár gyakori bajnoki forgatókönyv-műveleteit mutatják be.

Az alábbi minták az EventGridEvents és a CloudEvents közzétételével és felhasználásával dict foglalkoznak.

További minták itt találhatók.

  • A küldési forgatókönyvhöz kapcsolódó további mintákat itt tekinthet meg.
  • Ha további mintákat szeretne látni a különböző üzenetkezelési szolgáltatásokból származó hasznos adatok gépelt objektumként való felhasználásával kapcsolatban, látogasson el a Minták felhasználása oldalra.

További dokumentáció

A Azure Event Grid részletesebb dokumentációját az Event Grid docs.microsoft.com dokumentációjában találja.

Közreműködés

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. Részletekért látogasson el cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes olyan tárházban, amely a CLA-t használja.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.