Partager via

Azure Event Grid bibliothèque cliente pour Python - version 4.16.0

  • Article

Azure Event Grid est un service de routage d’événement intelligent et entièrement géré qui permet une consommation d’événements uniforme à l’aide d’un modèle publication-abonnement.

| Code sourcePackage (PyPI) | Package (Conda) | Documentation de référence sur les | API | Documentation produitÉchantillons | Changelog

Prise en main

Prérequis

  • Python 3.7 ou version ultérieure est requis pour utiliser ce package.
  • Vous devez disposer d’un abonnement Azure et d’une ressource de rubrique Event Grid pour utiliser ce package. Suivez ce tutoriel pas à pas pour inscrire le fournisseur de ressources Event Grid et créer des rubriques Event Grid à l’aide du Portail Azure. Il existe un tutoriel similaire à l’aide d’Azure CLI.

Installer le package

Installez la bibliothèque cliente Azure Event Grid pour Python avec pip :

pip install azure-eventgrid
  • Une rubrique ou un domaine Event Grid existant est requis. Vous pouvez créer la ressource à l’aide du portail Azure ou d’Azure CLI

Si vous utilisez Azure CLI, remplacez <resource-group-name> et <resource-name> par vos propres noms uniques.

Créer une rubrique Event Grid

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

Créer un domaine Event Grid

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

Authentifier le client

Pour interagir avec le service Event Grid, vous devez créer un instance d’un client. Un point de terminaison et des informations d’identification sont nécessaires pour instancier l’objet client.

Utilisation d’Azure Active Directory (AAD)

Azure Event Grid fournit l’intégration à Azure Active Directory (Azure AD) pour l’authentification basée sur l’identité des demandes. Avec Azure AD, vous pouvez utiliser le contrôle d’accès en fonction du rôle (RBAC) pour accorder l’accès à vos ressources Azure Event Grid à des utilisateurs, des groupes ou des applications.

Pour envoyer des événements à une rubrique ou un domaine avec un TokenCredential, le rôle « Expéditeur de données EventGrid » doit être attribué à l’identité authentifiée.

Avec le azure-identity package, vous pouvez autoriser en toute transparence les demandes dans les environnements de développement et de production. Pour en savoir plus sur Azure Active Directory, consultez LEazure-identity FICHIER README.

Par exemple, vous pouvez utiliser DefaultAzureCredential pour construire un client qui s’authentifiera à l’aide d’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)

Recherche du point de terminaison

Vous trouverez le point de terminaison de la rubrique dans la ressource Rubrique Event Grid sur le Portail Azure. Cela se présente comme suit : "https://<event-grid-topic-name>.<topic-location>.eventgrid.azure.net/api/events"

Créer le client avec AzureKeyCredential

Pour utiliser une clé d’accès comme credential paramètre, passez la clé en tant que chaîne dans un instance d’AzureKeyCredential.

Note: La clé d’accès se trouve dans le portail Azure dans le menu « Clés d’accès » de la ressource rubrique Event Grid. Ils peuvent également être obtenus via Azure CLI ou la azure-mgmt-eventgrid bibliothèque. Vous trouverez un guide pour obtenir des clés d’accès ici.

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)

Note: Un client peut également être authentifié via une signature SAP, à l’aide de AzureSasCredential. Un exemple illustrant cela est disponible ici (async_version).

Note: La generate_sas méthode peut être utilisée pour générer une signature d’accès partagé. Un exemple illustrant cela est visible ici.

Concepts clés

Rubrique

Une rubrique est un canal au sein du service EventGrid pour envoyer des événements. Le schéma d’événement qu’une rubrique accepte est décidé au moment de la création de la rubrique. Si des événements d’un type de schéma sont envoyés à une rubrique qui nécessite un autre type de schéma, des erreurs sont générées.

Domaine

Un domaine d’événements est un outil de gestion pour un grand nombre de rubriques Event Grid liées à la même application. Ils vous permettent de publier des événements dans des milliers de rubriques. Les domaines vous donnent également le contrôle d’autorisation et d’authentification sur chaque rubrique. Pour plus d’informations, consultez Vue d’ensemble du domaine d’événements.

Lorsque vous créez un domaine d’événements, un point de terminaison de publication pour ce domaine est mis à votre disposition. Ce processus est similaire à la création d’une rubrique Event Grid. La seule différence est que, lors de la publication dans un domaine, vous devez spécifier la rubrique dans le domaine auquel vous souhaitez que l’événement soit remis.

Schémas d’événement

Un événement est la plus petite quantité d’informations qui décrit entièrement un événement qui s’est produit dans le système. Lors de la création d’une rubrique ou d’un domaine personnalisé, vous devez spécifier le schéma qui sera utilisé lors de la publication d’événements.

Event Grid prend en charge plusieurs schémas pour les événements d’encodage.

Schéma Event Grid

Même si vous pouvez configurer votre rubrique pour utiliser un schéma personnalisé, il est plus courant d’utiliser le schéma Event Grid déjà défini. Consultez les spécifications et les exigences ici.

Schéma CloudEvents v1.0

Une autre option consiste à utiliser le schéma CloudEvents v1.0. CloudEvents est un projet Cloud Native Computing Foundation qui produit une spécification pour décrire les données d’événement d’une manière commune. Le résumé du service de CloudEvents est disponible ici.

EventGridPublisherClient

EventGridPublisherClient fournit des opérations pour envoyer des données d’événement à un nom d’hôte de rubrique spécifié lors de l’initialisation du client.

Quel que soit le schéma pour lequel votre rubrique ou domaine est configuré pour utiliser, EventGridPublisherClient sera utilisé pour publier des événements dans celui-ci. Utilisez les événements de publication de méthode send .

Les formats d’événements suivants sont autorisés à être envoyés :

  • Liste ou instance unique d’EventGridEvents fortement typés.

  • Représentation dict d’un objet EventGridEvent sérialisé.

  • Liste ou instance de CloudEvents fortement typés.

  • Représentation dict d’un objet CloudEvent sérialisé.

  • Représentation dictée d’un schéma personnalisé.

Consultez les exemples pour obtenir des exemples détaillés.

Note: Il est important de savoir si votre rubrique prend en charge CloudEvents ou EventGridEvents avant la publication. Si vous envoyez à une rubrique qui ne prend pas en charge le schéma de l’événement que vous envoyez, send() lève une exception.

Rubriques sur le système

Une rubrique système dans Event Grid représente un ou plusieurs événements publiés par les services Azure tels que Stockage Azure ou Azure Event Hubs. Par exemple, une rubrique système peut représenter tous les événements d’objets blob ou uniquement les événements de création et de suppression d’objets blob publiés pour un compte de stockage spécifique.

Les noms des différents types d’événements pour les événements système publiés sur Azure Event Grid sont disponibles dans azure.eventgrid.SystemEventNames. Pour obtenir la liste complète des rubriques système reconnaissables, consultez Rubriques système.

Pour plus d’informations sur les concepts clés sur Event Grid, consultez Concepts dans Azure Event Grid.

Event Grid sur Kubernetes avec Azure Arc

Event Grid sur Kubernetes avec Azure Arc est une offre qui vous permet d’exécuter Event Grid sur votre propre cluster Kubernetes. Cette fonctionnalité est activée par l’utilisation de Kubernetes avec Azure Arc. Via Kubernetes avec Azure Arc, un cluster Kubernetes pris en charge se connecte à Azure. Une fois connecté, vous pouvez installer Event Grid dessus. Cliquez ici pour en savoir plus.

Prise en charge des événements cloud CNCF

À compter de v4.7.0, ce package prend également en charge la publication d’un événement cloud CNCF à partir de https://pypi.org/project/cloudevents/. Vous pouvez passer un objet CloudEvent de cette bibliothèque à l’API send .


from cloudevents.http import CloudEvent

event = CloudEvent(...)

client.send(event)

Exemples

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches Event Grid les plus courantes, notamment :

Envoyer un événement Event Grid

Cet exemple publie un événement Event Grid.

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)

Envoyer un événement cloud

Cet exemple publie un événement 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)

Envoyer plusieurs événements

Il est possible d’envoyer des événements sous forme de lot lors de l’envoi de plusieurs événements à une rubrique ou un domaine. Cet exemple envoie une liste de CloudEvents à l’aide de la méthode send.

AVERTISSEMENT: Lors de l’envoi d’une liste de plusieurs événements à la fois, l’itération et l’envoi de chaque événement n’entraînent pas des performances optimales. Pour de meilleures performances, il est vivement recommandé d’envoyer une liste d’événements.

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)

Envoyer des événements en tant que dictionnaires

Une représentation dict des modèles sérialisés respectifs peut également être utilisée pour publier CloudEvent(s) ou EventGridEvent(s) en dehors des objets fortement typés.

Utilisez une représentation de type dict à envoyer à une rubrique avec un schéma personnalisé, comme illustré ci-dessous.

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)

Consommer à partir de la file d’attente de stockage

Cet exemple utilise un message reçu à partir de la file d’attente de stockage et le désérialise dans un objet 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]

Consommer à partir de Servicebus

Cet exemple utilise un message de charge utile reçu de ServiceBus et le désérialise dans un objet 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]

Suivi distribué avec EventGrid

Vous pouvez utiliser OpenTelemetry pour Python comme d’habitude avec EventGrid, car il est compatible avec l’intégration de suivi azure-core.

Voici un exemple d’utilisation d’OpenTelemetry pour suivre l’envoi d’un CloudEvent.

Tout d’abord, définissez OpenTelemetry comme plug-in de suivi activé pour EventGrid.

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

settings.tracing_implementation = OpenTelemetrySpan

Utilisation régulière de la télémétrie ouverte à partir d’ici. Pour plus d’informations, consultez OpenTelemetry . Cet exemple utilise un exportateur de console simple pour exporter les traces. N’importe quel exportateur peut être utilisé ici, y compris azure-monitor-opentelemetry-exporter, jaeger, zipkin etc.

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

Une fois les tracer et exporter définis, suivez l’exemple ci-dessous pour commencer à collecter des traces tout en utilisant la send méthode à partir de pour EventGridPublisherClient envoyer un objet 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)

Dépannage

  • Activez azure.eventgrid l’enregistreur d’événements pour collecter des traces à partir de la bibliothèque.

Général

La bibliothèque cliente Event Grid génère des exceptions définies dans Azure Core.

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.

Configuration facultative

Les arguments facultatifs mot clé peuvent être transmis au niveau du client et par opération. La documentation de référence azure-core décrit les configurations disponibles pour les nouvelles tentatives, la journalisation, les protocoles de transport, etc.

Étapes suivantes

La section suivante fournit plusieurs extraits de code illustrant les modèles courants utilisés dans l’API Python Event Grid.

Autres exemples de code

Ces exemples de code montrent les opérations courantes de scénario champion avec la bibliothèque cliente Azure Event Grid.

Les exemples suivants couvrent la publication et la consommation dict de représentations d’EventGridEvents et de CloudEvents.

Vous trouverez d’autres exemples ici.

  • D’autres exemples liés au scénario d’envoi sont disponibles ici.
  • Pour voir d’autres exemples liés à la consommation d’une charge utile à partir de différents services de messagerie en tant qu’objet typé, consultez Consommer des exemples

Documentation complémentaire

Pour obtenir une documentation plus complète sur Azure Event Grid, consultez la documentation Event Grid sur docs.microsoft.com.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.