Grade de Eventos do Azure biblioteca de clientes para Python – versão 4.17.0b1

  • Artigo

A Grade de Eventos do Azure é um serviço de roteamento de eventos inteligente totalmente gerenciado que permite um consumo de eventos uniforme usando um modelo do tipo publicar-assinar.

Código-fonte | Pacote (PyPI) | Pacote (Conda) | Documentação | de referência da APIDocumentação do produto | Amostras | Changelog

Aviso de isenção de responsabilidade

Essa é uma versão beta do EventGrid do EventGridClientAzure, que juntamente com o GA EventGridPublisherClient. EventGridClient dá publish_cloud_eventssuporte às operações , receive_cloud_events, acknowledge_cloud_eventsrelease_cloud_events, , reject_cloud_eventse renew_cloud_event_locks . Consulte os exemplos para obter mais informações.

Introdução

Pré-requisitos

Instalar o pacote

Instale a biblioteca de clientes Grade de Eventos do Azure para Python com pip:

pip install azure-eventgrid

Se você usar a CLI do Azure, substitua <resource-group-name> e <resource-name> por seus próprios nomes exclusivos.

Criar um tópico da Grade de Eventos

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

Criar um domínio de grade de eventos

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

Autenticar o cliente

Para interagir com o serviço da Grade de Eventos, você precisará criar uma instância de um cliente. Um ponto de extremidade e uma credencial são necessários para instanciar o objeto cliente.

Usando o AAD (Azure Active Directory)

Grade de Eventos do Azure fornece integração com o Azure Active Directory (Azure AD) para autenticação baseada em identidade de solicitações. Com Azure AD, você pode usar o RBAC (controle de acesso baseado em função) para conceder acesso aos recursos Grade de Eventos do Azure aos usuários, grupos ou aplicativos.

Para enviar eventos para um tópico ou domínio com um TokenCredential, a identidade autenticada deve ter a função "EventGrid Data Sender" atribuída.

Com o azure-identity pacote, você pode autorizar diretamente solicitações em ambientes de desenvolvimento e produção. Para saber mais sobre o Azure Active Directory, consulte o azure-identity LEIAME.

Por exemplo, você pode usar DefaultAzureCredential para construir um cliente que será autenticado usando o 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)

Pesquisando o ponto de extremidade

Você pode encontrar o ponto de extremidade do tópico no recurso Tópico da Grade de Eventos no portal do Azure. Isso terá a seguinte aparência: "https://<event-grid-topic-name>.<topic-location>.eventgrid.azure.net/api/events"

Criar o cliente com AzureKeyCredential

Para usar uma chave do Access como parâmetro credential , passe a chave como uma cadeia de caracteres para uma instância do AzureKeyCredential.

Nota: A Chave de Acesso pode ser encontrada no portal do azure no menu "Chaves de Acesso" do recurso Tópico da Grade de Eventos. Eles também podem ser obtidos por meio da CLI do azure ou da azure-mgmt-eventgrid biblioteca. Um guia para obter chaves de acesso pode ser encontrado aqui.

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)

Nota: Um cliente também pode ser autenticado por meio da assinatura SAS, usando o AzureSasCredential. Um exemplo que demonstra isso está disponível aqui (async_version).

Nota: O generate_sas método pode ser usado para gerar uma assinatura de acesso compartilhado. Um exemplo que demonstra isso pode ser visto aqui.

Principais conceitos

Tópico

Um tópico é um canal dentro do serviço EventGrid para enviar eventos. O esquema de evento que um tópico aceita é decidido no momento da criação do tópico. Se eventos de um tipo de esquema forem enviados para um tópico que exija um tipo de esquema diferente, erros serão gerados.

Domínio

Um domínio de evento é uma ferramenta de gerenciamento para um grande número de tópicos da Grade de Eventos relacionados ao mesmo aplicativo. Com eles, é possível publicar eventos em milhares de tópicos. Os domínios também oferecem a você controle de autorização e autenticação sobre cada tópico. Para obter mais informações, visite Visão geral do domínio de eventos.

Quando você cria um domínio de evento, um ponto de extremidade de publicação para esse domínio é disponibilizado para você. Esse processo é semelhante à criação de um Tópico da Grade de Eventos. A única diferença é que, ao publicar em um domínio, você deve especificar o tópico dentro do domínio ao qual deseja que o evento seja entregue.

Esquemas de evento

Um evento é a menor quantidade de informações que descreve totalmente algo que aconteceu no sistema. Quando um tópico ou domínio personalizado é criado, você deve especificar o esquema que será usado ao publicar eventos.

A Grade de Eventos dá suporte a vários esquemas para eventos de codificação.

Esquema da Grade de Eventos

Embora você possa configurar seu tópico para usar um esquema personalizado, é mais comum usar o esquema da Grade de Eventos já definido. Confira as especificações e os requisitos aqui.

Esquema do CloudEvents v 1.0

Outra opção é usar o esquema CloudEvents v1.0. CloudEvents é um projeto do Cloud Native Computing Foundation que produz uma especificação para descrever dados de evento de maneira comum. O resumo do serviço de CloudEvents pode ser encontrado aqui.

EventGridPublisherClient

EventGridPublisherClient fornece operações para enviar dados de evento para um nome de host de tópico especificado durante a inicialização do cliente.

Independentemente do esquema que seu tópico ou domínio está configurado para usar, EventGridPublisherClient será usado para publicar eventos nele. Use o send método de publicação de eventos.

Os seguintes formatos de eventos têm permissão para serem enviados:

  • Uma lista ou uma única instância de EventGridEvents fortemente tipado.

  • Uma representação de ditado de um objeto EventGridEvent serializado.

  • Uma lista ou uma única instância de CloudEvents fortemente tipado.

  • Uma representação de ditado de um objeto CloudEvent serializado.

  • Uma representação de ditado de qualquer Esquema Personalizado.

Confira os exemplos para obter exemplos detalhados.

Nota: É importante saber se seu tópico dá suporte a CloudEvents ou EventGridEvents antes da publicação. Se você enviar para um tópico que não dá suporte ao esquema do evento que está enviando, send() lançará uma exceção.

Tópicos do sistema

Um tópico do sistema na Grade de Eventos representa um ou mais eventos publicados pelos serviços do Azure, como Armazenamento do Azure ou Hubs de Eventos do Azure. Por exemplo, um tópico do sistema pode representar todos os eventos de blob ou apenas eventos de criação de blob e exclusão de blob publicados para uma conta de armazenamento específica.

Os nomes dos vários tipos de eventos para os eventos do sistema publicados no Grade de Eventos do Azure estão disponíveis em azure.eventgrid.SystemEventNames. Para obter uma lista completa de tópicos reconhecíveis do sistema, visite Tópicos do Sistema.

Para obter mais informações sobre os principais conceitos na Grade de Eventos, consulte Conceitos em Grade de Eventos do Azure.

Grade de Eventos no Kubernetes com o Azure Arc

A Grade de Eventos no Kubernetes com o Azure Arc é uma oferta que permite que você execute a Grade de Eventos em seu próprio cluster do Kubernetes. Essa funcionalidade é habilitada pelo uso de Kubernetes habilitado para Azure Arc. Através de Kubernetes habilitado para Azure Arc, um cluster do Kubernetes com suporte se conecta ao Azure. Uma vez conectado, você poderá instalar a Grade de Eventos. Leia mais sobre isso aqui.

Suporte para eventos de nuvem CNCF

A partir da v4.7.0, esse pacote também dá suporte à publicação de um evento de nuvem CNCF do https://pypi.org/project/cloudevents/. Você poderia passar um objeto CloudEvent dessa biblioteca para a send API.


from cloudevents.http import CloudEvent

event = CloudEvent(...)

client.send(event)

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns da Grade de Eventos, incluindo:

Enviar um evento da Grade de Eventos

Este exemplo publica um evento da Grade de Eventos.

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)

Enviar um evento de nuvem

Este exemplo publica um evento na nuvem.

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)

Enviar vários eventos

É possível enviar eventos como um lote ao enviar vários eventos para um tópico ou um domínio. Este exemplo envia uma lista de CloudEvents usando o método send.

AVISO: Ao enviar uma lista de vários eventos ao mesmo tempo, iterar e enviar cada evento não resultará em um desempenho ideal. Para obter o melhor desempenho, é altamente recomendável enviar uma lista de eventos.

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)

Enviar eventos como dicionários

Uma representação de ditado dos respectivos modelos serializados também pode ser usada para publicar CloudEvent(s) ou EventGridEvent(s) além dos objetos fortemente tipados.

Use uma representação semelhante a um ditado para enviar para um tópico com esquema personalizado, conforme mostrado abaixo.

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)

Consumir da fila de armazenamento

Este exemplo consome uma mensagem recebida da fila de armazenamento e a desserializa em um objeto 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]

Consumir do servicebus

Este exemplo consome uma mensagem de conteúdo recebida do ServiceBus e a desserializa em um objeto 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]

Rastreamento distribuído com EventGrid

Você pode usar o OpenTelemetry para Python como de costume com o EventGrid, pois ele é compatível com a integração de rastreamento do azure-core.

Aqui está um exemplo de como usar o OpenTelemetry para rastrear o envio de um CloudEvent.

Primeiro, defina OpenTelemetry como plug-in de rastreamento habilitado para EventGrid.

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

settings.tracing_implementation = OpenTelemetrySpan

Uso regular de telemetria aberta aqui. Consulte OpenTelemetry para obter detalhes. Este exemplo usa um exportador de console simples para exportar os rastreamentos. Qualquer exportador pode ser usado aqui, incluindo azure-monitor-opentelemetry-exporter, jaegeretc 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)
)

Depois que o tracer e exporter estiverem definidos, siga o exemplo abaixo para começar a coletar rastreamentos enquanto usa o send método do EventGridPublisherClient para enviar um objeto 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)

Solução de problemas

  • Habilite azure.eventgrid o agente para coletar rastreamentos da biblioteca.

Geral

A biblioteca de clientes da Grade de Eventos gerará exceções definidas no Azure Core.

Registro em log

Essa biblioteca usa a biblioteca de log padrão para registro em log. Informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível INFO.

Configuração opcional

Argumentos opcionais de palavra-chave podem ser passados no nível do cliente e por operação. A documentação de referência do azure-core descreve as configurações disponíveis para repetições, registro em log, protocolos de transporte e muito mais.

Próximas etapas

A seção a seguir fornece vários snippets de código ilustrando padrões comuns usados na API python da Grade de Eventos.

Mais códigos de exemplo

Esses exemplos de código mostram operações de cenário de campeão comuns com a biblioteca de clientes Grade de Eventos do Azure.

Os exemplos a seguir abordam a publicação e o consumo dict de representações de EventGridEvents e CloudEvents.

Mais amostras podem ser encontradas aqui.

  • Mais exemplos relacionados ao cenário de envio podem ser vistos aqui.
  • Para ver mais exemplos relacionados ao consumo de uma carga de diferentes serviços de mensagens como um objeto tipado, visite Consumir Exemplos

Documentação adicional

Para obter uma documentação mais abrangente sobre Grade de Eventos do Azure, consulte a documentação da Grade de Eventos sobre docs.microsoft.com.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.