Azure Event Grid pustaka klien untuk Python - versi 4.16.0

  • Artikel

Azure Event Grid adalah layanan perutean peristiwa cerdas yang dikelola sepenuhnya yang memungkinkan konsumsi peristiwa yang seragam menggunakan model terbitkan-berlangganan.

Kode sumber | Paket (PyPI) | Paket (Conda) | Dokumentasi | referensi APIDokumentasi | produkSampel | Changelog

Memulai

Prasyarat

Instal paketnya

Instal pustaka klien Azure Event Grid untuk Python dengan pip:

pip install azure-eventgrid

Jika Anda menggunakan Azure CLI, ganti <resource-group-name> dan <resource-name> dengan nama unik Anda sendiri.

Membuat Topik Event Grid

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

Membuat Domain Event Grid

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

Mengautentikasi klien

Untuk berinteraksi dengan layanan Event Grid, Anda harus membuat instans klien. Titik akhir dan kredensial diperlukan untuk membuat instans objek klien.

Menggunakan Azure Active Directory (AAD)

Azure Event Grid menyediakan integrasi dengan Azure Active Directory (Azure AD) untuk autentikasi permintaan berbasis identitas. Dengan Azure AD, Anda dapat menggunakan kontrol akses berbasis peran (RBAC) untuk memberikan akses ke sumber daya Azure Event Grid Anda kepada pengguna, grup, atau aplikasi.

Untuk mengirim peristiwa ke topik atau domain dengan , identitas yang TokenCredentialdiautentikasi harus memiliki peran "Pengirim Data EventGrid" yang ditetapkan.

Dengan paket ini azure-identity , Anda dapat mengotorisasi permintaan dengan mulus di lingkungan pengembangan dan produksi. Untuk mempelajari selengkapnya tentang Azure Active Directory, lihat azure-identity README.

Misalnya, Anda dapat menggunakan DefaultAzureCredential untuk membuat klien yang akan mengautentikasi menggunakan 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)

Mencari titik akhir

Anda dapat menemukan titik akhir topik dalam sumber daya Topik Event Grid di portal Azure. Ini akan terlihat seperti: "https://<event-grid-topic-name>.<topic-location>.eventgrid.azure.net/api/events"

Membuat klien dengan AzureKeyCredential

Untuk menggunakan kunci Access sebagai credential parameter, teruskan kunci sebagai string ke dalam instans AzureKeyCredential.

Catatan: Kunci Akses dapat ditemukan di portal microsoft azure di menu "Kunci Akses" dari sumber daya Topik Event Grid. Mereka juga dapat diperoleh melalui azure CLI, atau azure-mgmt-eventgrid pustaka. Panduan untuk mendapatkan kunci akses dapat ditemukan di sini.

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)

Catatan: Klien juga dapat diautentikasi melalui tanda tangan SAS, menggunakan AzureSasCredential. Sampel yang menunjukkan ini, tersedia di sini (async_version).

Catatan: Metode generate_sas ini dapat digunakan untuk menghasilkan tanda tangan akses bersama. Sampel yang menunjukkan ini dapat dilihat di sini.

Konsep utama

Topik

Topik adalah saluran dalam layanan EventGrid untuk mengirim peristiwa. Skema peristiwa yang diterima topik diputuskan pada waktu pembuatan topik. Jika peristiwa jenis skema dikirim ke topik yang memerlukan jenis skema yang berbeda, kesalahan akan dimunculkan.

Domain

Domain peristiwa adalah alat manajemen untuk sejumlah besar topik Event Grid yang terkait dengan aplikasi yang sama. Mereka memungkinkan Anda untuk menerbitkan kejadian ke ribuan topik. Domain juga memberi Anda kontrol otorisasi dan autentikasi atas setiap topik. Untuk informasi selengkapnya, kunjungi Gambaran umum domain peristiwa.

Saat Anda membuat domain peristiwa, titik akhir penerbitan untuk domain ini tersedia untuk Anda. Proses ini mirip dengan membuat Topik Event Grid. Satu-satunya perbedaan adalah bahwa, saat menerbitkan ke domain, Anda harus menentukan topik dalam domain yang Anda inginkan untuk disampaikan peristiwa tersebut.

Skema acara

Peristiwa adalah jumlah informasi terkecil yang sepenuhnya menjelaskan sesuatu yang terjadi dalam sistem. Saat topik atau domain kustom dibuat, Anda harus menentukan skema yang akan digunakan saat menerbitkan peristiwa.

Event Grid mendukung beberapa skema untuk mengodekan peristiwa.

Skema Event Grid

Meskipun Anda dapat mengonfigurasi topik Anda untuk menggunakan skema kustom, lebih umum untuk menggunakan skema Event Grid yang sudah ditentukan. Lihat spesifikasi dan persyaratan di sini.

Skema CloudEvents v1.0

Opsi lain adalah menggunakan skema CloudEvents v1.0. CloudEvents adalah proyek Cloud Native Computing Foundation yang menghasilkan spesifikasi untuk menjelaskan data peristiwa dengan cara yang sama. Ringkasan layanan CloudEvents dapat ditemukan di sini.

EventGridPublisherClient

EventGridPublisherClient menyediakan operasi untuk mengirim data peristiwa ke nama host topik yang ditentukan selama inisialisasi klien.

Terlepas dari skema yang dikonfigurasi untuk digunakan oleh topik atau domain Anda, EventGridPublisherClient akan digunakan untuk menerbitkan peristiwa ke dalamnya. send Gunakan metode penerbitan peristiwa.

Format peristiwa berikut diizinkan untuk dikirim:

  • Daftar atau satu instans EventGridEvents yang ditik dengan kuat.

  • Representasi dict dari objek EventGridEvent berseri.

  • Daftar atau satu instans CloudEvents yang ditik dengan kuat.

  • Representasi dict dari objek CloudEvent berseri.

  • Representasi dict dari Skema Kustom apa pun.

Silakan lihat sampel untuk contoh terperinci.

Catatan: Penting untuk mengetahui apakah topik Anda mendukung CloudEvents atau EventGridEvents sebelum menerbitkan. Jika Anda mengirim ke topik yang tidak mendukung skema peristiwa yang Anda kirim, send() akan memberikan pengecualian.

Topik Sistem

Topik sistem di Event Grid mewakili satu atau beberapa peristiwa yang diterbitkan oleh layanan Azure seperti Azure Storage atau Azure Event Hubs. Misalnya, topik sistem dapat mewakili semua peristiwa blob atau hanya peristiwa pembuatan blob dan penghapusan blob yang diterbitkan untuk akun penyimpanan tertentu.

Nama berbagai jenis peristiwa untuk peristiwa sistem yang diterbitkan ke Azure Event Grid tersedia di azure.eventgrid.SystemEventNames. Untuk daftar lengkap topik sistem yang dapat dikenali, kunjungi Topik Sistem.

Untuk informasi selengkapnya tentang konsep utama di Event Grid, lihat Konsep di Azure Event Grid.

Event Grid di Kubernetes dengan Azure Arc

Event Grid di Kubernetes dengan Azure Arc adalah penawaran yang memungkinkan Anda menjalankan Event Grid di kluster Kubernetes sendiri. Kemampuan ini diaktifkan dengan penggunaan Kuberneters yang diaktifkan Azure Arc. Melalui Kubernetes yang diaktifkan Azure Arc, kluster Kubernetes yang didukung terhubung ke Azure. Setelah terhubung, Anda dapat menginstal Event Grid. Baca selengkapnya mengenai hal ini di sini.

Dukungan untuk Peristiwa Cloud CNCF

Dimulai dengan v4.7.0, paket ini juga mendukung penerbitan peristiwa cloud CNCF dari https://pypi.org/project/cloudevents/. Anda akan dapat meneruskan objek CloudEvent dari pustaka ini ke send API.


from cloudevents.http import CloudEvent

event = CloudEvent(...)

client.send(event)

Contoh

Bagian berikut ini menyediakan beberapa cuplikan kode yang mencakup beberapa tugas Event Grid yang paling umum, termasuk:

Mengirim Peristiwa Event Grid

Contoh ini menerbitkan peristiwa 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)

Mengirim Peristiwa Cloud

Contoh ini menerbitkan peristiwa 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)

Kirim Beberapa peristiwa

Dimungkinkan untuk mengirim peristiwa sebagai batch saat mengirim beberapa peristiwa ke topik atau domain. Contoh ini mengirimkan daftar CloudEvents menggunakan metode kirim.

PERINGATAN: Saat mengirim daftar beberapa peristiwa sekaligus, iterasi dan pengiriman setiap peristiwa tidak akan menghasilkan performa yang optimal. Untuk performa terbaik, sangat disarankan untuk mengirim daftar peristiwa.

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)

Mengirim peristiwa sebagai kamus

Representasi dict dari masing-masing model berseri juga dapat digunakan untuk menerbitkan CloudEvent atau EventGridEvent selain dari objek yang diketik dengan kuat.

Gunakan representasi seperti dikte untuk mengirim ke topik dengan skema kustom seperti yang ditunjukkan di bawah ini.

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)

Mengonsumsi dari antrean penyimpanan

Contoh ini menggunakan pesan yang diterima dari antrean penyimpanan dan mendeserialisasinya ke objek 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]

Mengonsumsi dari servicebus

Contoh ini menggunakan pesan payload yang diterima dari ServiceBus dan mendeserialisasinya ke objek 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]

Pelacakan Terdistribusi dengan EventGrid

Anda dapat menggunakan OpenTelemetry untuk Python seperti biasa dengan EventGrid karena kompatibel dengan integrasi pelacakan azure-core.

Berikut adalah contoh penggunaan OpenTelemetry untuk melacak pengiriman CloudEvent.

Pertama, atur OpenTelemetry sebagai plugin pelacakan yang diaktifkan untuk EventGrid.

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

settings.tracing_implementation = OpenTelemetrySpan

Penggunaan telemetri terbuka reguler dari sini. Lihat OpenTelemetry untuk detailnya. Contoh ini menggunakan pengekspor konsol sederhana untuk mengekspor jejak. Setiap pengekspor dapat digunakan di sini termasuk azure-monitor-opentelemetry-exporter, , jaegerzipkin dll.

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 Setelah dan exporter diatur, silakan ikuti contoh di bawah ini untuk mulai mengumpulkan jejak saat menggunakan send metode dari EventGridPublisherClient untuk mengirim objek 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)

Pemecahan Masalah

  • Aktifkan azure.eventgrid pencatat untuk mengumpulkan jejak dari pustaka.

Umum

Pustaka klien Event Grid akan memunculkan pengecualian yang ditentukan di Azure Core.

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Konfigurasi Opsional

Argumen kata kunci opsional dapat diteruskan di tingkat klien dan per operasi. Dokumentasi referensi azure-core menjelaskan konfigurasi yang tersedia untuk percobaan ulang, pengelogan, protokol transportasi, dan banyak lagi.

Langkah berikutnya

Bagian berikut menyediakan beberapa cuplikan kode yang mengilustrasikan pola umum yang digunakan dalam Api Python Event Grid.

Lebih banyak kode sampel

Sampel kode ini menunjukkan operasi skenario juara umum dengan pustaka klien Azure Event Grid.

Sampel berikut mencakup penerbitan dan penggunaan dict representasi EventGridEvents dan CloudEvents.

Sampel lainnya dapat ditemukan di sini.

  • Lebih banyak sampel yang terkait dengan skenario pengiriman dapat dilihat di sini.
  • Untuk melihat lebih banyak sampel yang terkait dengan mengonsumsi payload dari layanan olahpesan yang berbeda sebagai objek yang ditik, kunjungi Mengonsumsi Sampel

Dokumentasi tambahan

Untuk dokumentasi yang lebih luas tentang Azure Event Grid, lihat dokumentasi Event Grid di docs.microsoft.com.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.