Bagikan melalui

Pustaka klien Azure Event Grid untuk JavaScript - versi 5.12.0

azure Event Grid adalah layanan berbasis cloud yang menyediakan pengiriman peristiwa yang andal dalam skala besar.

Gunakan pustaka klien untuk:

  • Mengirim peristiwa ke Event Grid menggunakan skema Event Grid, Cloud Events 1.0, atau skema kustom
  • Mendekode dan memproses peristiwa yang dikirimkan ke penanganan Event Grid
  • Membuat Tanda Tangan Akses Bersama untuk topik Event Grid

Tautan kunci:

Persiapan

Lingkungan yang saat ini didukung

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

  • Langganan Azure .
  • Topik atau Domain Event Grid yang ada. Jika Anda perlu membuat sumber daya, Anda dapat menggunakan Portal Microsoft Azure atau Azure CLI.

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

Membuat Topik Event Grid

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

Membuat Domain Event Grid

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

Menginstal paket @azure/eventgrid

Instal pustaka klien Azure Event Grid untuk JavaScript dengan npm:

npm install @azure/eventgrid

Membuat dan mengautentikasi EventGridPublisherClient

Untuk membuat objek klien untuk mengakses API Event Grid, Anda memerlukan endpoint topik Event Grid dan credential. Klien Event Grid dapat menggunakan Kunci Akses atau Tanda Tangan Akses Bersama (SAS) yang dibuat dari kunci akses.

Anda dapat menemukan titik akhir untuk topik Event Grid Anda baik di Portal Azure atau dengan menggunakan cuplikan Azure CLI di bawah ini:

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

Menggunakan Kunci Akses

Gunakan Portal Azure untuk menelusuri ke sumber daya Event Grid Anda dan mengambil Kunci Akses, atau gunakan cuplikan Azure CLI di bawah ini:

az eventgrid topic key list --resource-group <your-resource-group-name> --name <your-event-grid-topic-name>

Setelah Anda memiliki kunci API dan titik akhir, Anda dapat menggunakan kelas AzureKeyCredential untuk mengautentikasi klien sebagai berikut:

import { EventGridPublisherClient, AzureKeyCredential } from "@azure/eventgrid";

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<Access Key>"),
);

Menggunakan Token SAS

Seperti kunci akses, token SAS memungkinkan akses untuk mengirim peristiwa ke topik Event Grid. Tidak seperti kunci akses, yang dapat digunakan sampai diregenerasi, token SAS memiliki waktu kedaluwarsa, di mana token tersebut tidak lagi valid. Untuk menggunakan token SAS untuk autentikasi, gunakan AzureSASCredential sebagai berikut:

import { EventGridPublisherClient, AzureSASCredential } from "@azure/eventgrid";

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureSASCredential("<SAS Token>"),
);

Anda dapat menghasilkan token SAS dengan menggunakan fungsi generateSharedAccessSigniture.

import { generateSharedAccessSignature, AzureKeyCredential } from "@azure/eventgrid";

// Create a SAS Token which expires on 2020-01-01 at Midnight.
const token = generateSharedAccessSignature(
  "<endpoint>",
  new AzureKeyCredential("<API key>"),
  new Date("2020-01-01T00:00:00"),
);

Menggunakan Azure Active Directory (AAD)

Azure EventGrid 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 TokenCredential, identitas terautentikasi harus memiliki peran "Pengirim Data EventGrid" yang ditetapkan.

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

Misalnya, penggunaan dapat menggunakan DefaultAzureCredential untuk membuat klien yang akan mengautentikasi menggunakan Azure Active Directory:

import { EventGridPublisherClient } from "@azure/eventgrid";
import { DefaultAzureCredential } from "@azure/identity";

const client = new EventGridPublisherClient(
  "<endpoint>",
  "CloudEvent",
  new DefaultAzureCredential(),
);

Konsep utama

EventGridPublisherClient

EventGridPublisherClient digunakan untuk mengirim peristiwa ke Topik Event Grid atau Domain Event Grid.

Skema Peristiwa

Event Grid mendukung beberapa skema untuk mengodekan peristiwa. Saat Topik Kustom atau Domain dibuat, Anda menentukan skema yang akan digunakan saat menerbitkan peristiwa. Meskipun Anda dapat mengonfigurasi topik Anda untuk menggunakan skema kustom lebih umum menggunakan skema Event Grid yang sudah ditentukan atau skema CloudEvents 1.0 . CloudEvents adalah proyek Cloud Native Computing Foundation yang menghasilkan spesifikasi untuk menjelaskan data peristiwa dengan cara yang sama. Saat Anda membuat EventGridPublisherClient, Anda harus menentukan skema mana yang dikonfigurasi untuk digunakan oleh topik Anda:

Jika topik Anda dikonfigurasi untuk menggunakan Skema Event Grid, atur "EventGrid" sebagai jenis skema:

import { EventGridPublisherClient } from "@azure/eventgrid";
import { DefaultAzureCredential } from "@azure/identity";

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new DefaultAzureCredential(),
);

Jika topik Anda dikonfigurasi untuk menggunakan Skema Peristiwa Cloud, atur "CloudEvent" sebagai jenis skema:

import { EventGridPublisherClient } from "@azure/eventgrid";
import { DefaultAzureCredential } from "@azure/identity";

const client = new EventGridPublisherClient(
  "<endpoint>",
  "CloudEvent",
  new DefaultAzureCredential(),
);

Jika topik Anda dikonfigurasi untuk menggunakan Skema Peristiwa Kustom, atur "Kustom" sebagai jenis skema:

import { EventGridPublisherClient } from "@azure/eventgrid";
import { DefaultAzureCredential } from "@azure/identity";

const client = new EventGridPublisherClient("<endpoint>", "Custom", new DefaultAzureCredential());

Membangun klien dengan skema yang berbeda dari apa yang topik dikonfigurasi untuk diharapkan akan mengakibatkan kesalahan dari layanan dan peristiwa Anda tidak akan diterbitkan.

Anda dapat melihat skema input apa yang telah dikonfigurasi untuk topik Event Grid dengan menggunakan cuplikan Azure CLI di bawah ini:

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "inputSchema"

EventGridDeserializer

Peristiwa yang dikirimkan kepada konsumen oleh Event Grid dikirimkan sebagai JSON. Tergantung pada jenis konsumen yang dikirimkan, layanan Event Grid dapat mengirimkan satu atau beberapa peristiwa sebagai bagian dari satu payload. Meskipun peristiwa ini dapat dideserialisasi menggunakan metode JavaScript normal seperti JSON.parse, pustaka ini menawarkan jenis pembantu untuk mendeserialisasi peristiwa, yang disebut EventGridDeserializer.

Dibandingkan dengan menggunakan JSON.parse secara langsung, EventGridDeserializer melakukan beberapa konversi tambahan saat deserializng peristiwa:

  1. EventGridDeserializer memvalidasi bahwa properti acara yang diperlukan ada dan merupakan jenis yang tepat.
  2. EventGridDeserializer mengonversi properti waktu peristiwa menjadi objek Date JavaScript.
  3. Saat menggunakan Cloud Events, data biner dapat digunakan untuk properti data peristiwa (dengan menggunakan Uint8Array). Ketika peristiwa dikirim melalui Event Grid, peristiwa tersebut dikodekan di Base 64. EventGridDeserializer akan mendekode data ini kembali ke instans Uint8Array.
  4. Saat mendeserilisasi Peristiwa Sistem (peristiwa yang dihasilkan oleh layanan Azure lain), akan melakukan konversi tambahan sehingga objek cocok dengan antarmuka terkait yang menjelaskan datanya. Saat menggunakan TypeScript, antarmuka ini memastikan Anda memiliki pengetikan yang kuat saat mengakses properti objek data untuk peristiwa sistem.

Saat membuat instans EventGridDeserializer Anda dapat menyediakan deserializer kustom yang digunakan untuk mengonversi objek data lebih lanjut.

Pelacakan Terdistribusi dan Peristiwa Cloud

Pustaka ini mendukung pelacakan terdistribusi menggunakan @azure/core-tracing. Saat menggunakan pelacakan terdistribusi, pustaka ini akan membuat rentang selama operasi send. Selain itu, saat mengirim peristiwa menggunakan skema Cloud Events 1.0, SDK akan menambahkan metadata pelacakan terdistribusi ke peristiwa menggunakan ekstensi Pelacakan Terdistribusi . Nilai untuk properti ekstensi traceparent dan tracestate sesuai dengan header traceparent dan tracestate dari permintaan HTTP yang mengirim peristiwa. Jika peristiwa sudah memiliki properti ekstensi traceparent, peristiwa tersebut tidak diperbarui.

Event Grid di Kubernetes

Pustaka ini telah diuji dan divalidasi pada Kubernetes menggunakan Azure Arc.

Contoh

Menerbitkan Peristiwa Kustom ke Topik Event Grid menggunakan Skema Event Grid

import { EventGridPublisherClient } from "@azure/eventgrid";
import { DefaultAzureCredential } from "@azure/identity";

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new DefaultAzureCredential(),
);

await client.send([
  {
    eventType: "Azure.Sdk.SampleEvent",
    subject: "Event Subject",
    dataVersion: "1.0",
    data: {
      hello: "world",
    },
  },
]);

Menerbitkan Peristiwa Kustom ke Topik di Domain Event Grid menggunakan Skema Event Grid

Menerbitkan peristiwa ke Domain Event Grid mirip dengan publikasi ke Topik Event Grid, kecuali bahwa saat menggunakan skema Event Grid untuk peristiwa, Anda harus menyertakan properti topic. Saat menerbitkan peristiwa dalam skema Cloud Events 1.0, properti source yang diperlukan digunakan sebagai nama topik di domain untuk diterbitkan ke:

import { EventGridPublisherClient } from "@azure/eventgrid";
import { DefaultAzureCredential } from "@azure/identity";

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new DefaultAzureCredential(),
);

await client.send([
  {
    topic: "my-sample-topic",
    eventType: "Azure.Sdk.SampleEvent",
    subject: "Event Subject",
    dataVersion: "1.0",
    data: {
      hello: "world",
    },
  },
]);

Mendeserialisasi Peristiwa

EventGridDeserializer dapat digunakan untuk mendeserialisasi peristiwa yang dikirimkan oleh Event Grid. Dalam contoh ini kita memiliki peristiwa cloud yang dideserialisasi menggunakan EventGridDeserializer dan menggunakan isSystemEvent untuk mendeteksi jenis peristiwa tersebut.

import { EventGridDeserializer, isSystemEvent } from "@azure/eventgrid";

const deserializer = new EventGridDeserializer();
const message = {
  id: "5bc888aa-c2f4-11ea-b3de-0242ac130004",
  source:
    "/subscriptions/<subscriptionid>/resourceGroups/dummy-rg/providers/Microsoft.EventGrid/topics/dummy-topic",
  specversion: "1.0",
  type: "Microsoft.ContainerRegistry.ImagePushed",
  subject: "Test Subject",
  time: "2020-07-10T21:27:12.925Z",
  data: {
    hello: "world",
  },
};
const deserializedMessage = await deserializer.deserializeCloudEvents(message);
console.log(deserializedMessage);
if (
  deserializedMessage != null &&
  deserializedMessage.length !== 0 &&
  isSystemEvent("Microsoft.ContainerRegistry.ImagePushed", deserializedMessage[0])
) {
  console.log("This is a Microsoft.ContainerRegistry.ImagePushed event");
}

Pemecahan masalah

Penebangan

Mengaktifkan pengelogan dapat membantu mengungkap informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/pencatat.

Langkah berikutnya

Silakan lihat sampel direktori untuk contoh terperinci tentang cara menggunakan pustaka ini.

Berkontribusi

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

  • Last updated on