Klientská knihovna Azure Event Gridu pro JavaScript – verze 5.5.1

Azure Event Grid je cloudová služba, která poskytuje spolehlivé doručování událostí ve velkém měřítku.

Klientskou knihovnu použijte k:

  • Odesílání událostí do Event Gridu pomocí schémat Event Gridu, cloudových událostí 1.0 nebo vlastního schématu
  • Dekódování a zpracování událostí, které byly doručeny obslužné rutině Event Gridu
  • Generování sdílených přístupových podpisů pro témata event gridu

Klíčové odkazy:

  • zdrojového kódu
  • balíčku (NPM)
  • Referenční dokumentace k rozhraní API
  • dokumentace k produktu
  • ukázky

Začínáme

Aktuálně podporovaná prostředí

Další podrobnosti najdete v našich zásadách podpory .

Požadavky

Pokud používáte Azure CLI, nahraďte <your-resource-group-name> a <your-resource-name> vlastními jedinečnými názvy:

Vytvoření tématu Event Gridu

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

Vytvoření domény Event Gridu

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

Instalace balíčku @azure/eventgrid

Nainstalujte klientskou knihovnu Azure Event Grid pro JavaScript s npm:

npm install @azure/eventgrid

Vytvoření a ověření EventGridPublisherClient

K vytvoření objektu klienta pro přístup k rozhraní API služby Event Grid budete potřebovat endpoint tématu Event Gridu a credential. Klient Event Gridu může použít přístupový klíč nebo sdílený přístupový podpis (SAS) vytvořený z přístupového klíče.

Koncový bod tématu služby Event Grid najdete na webu azure Portal nebo pomocí fragmentu kódu Azure CLI níže:

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

Použití přístupového klíče

Pomocí webu Azure Portal přejděte k prostředku služby Event Grid a načtěte přístupový klíč nebo použijte azure CLI fragment kódu níže:

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

Jakmile máte klíč rozhraní API a koncový bod, můžete k ověření klienta použít třídu AzureKeyCredential následujícím způsobem:

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

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

Použití tokenu SAS

Podobně jako přístupový klíč token SAS umožňuje přístup k odesílání událostí do tématu Event Gridu. Na rozdíl od přístupového klíče, který lze použít, dokud se nevygeneruje, má token SAS dobu experace, v jakém okamžiku už není platný. Pokud chcete k ověřování použít token SAS, použijte AzureSASCredential následujícím způsobem:

const { EventGridPublisherClient, AzureSASCredential } = require("@azure/eventgrid");

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

Token SAS můžete vygenerovat pomocí funkce generateSharedAccessSigniture.

const { generateSharedAccessSignature, AzureKeyCredential } = require("@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")
);

Použití Azure Active Directory (AAD)

Azure EventGrid poskytuje integraci se službou Azure Active Directory (Azure AD) pro ověřování požadavků na základě identit. Pomocí Azure AD můžete pomocí řízení přístupu na základě role (RBAC) udělit přístup k prostředkům Azure Event Gridu uživatelům, skupinám nebo aplikacím.

Pokud chcete odesílat události do tématu nebo domény s TokenCredential, měla by mít ověřená identita přiřazenou roli EventGrid Data Sender.

S balíčkem @azure/identity můžete bez problémů autorizovat požadavky v vývojových i produkčních prostředích. Další informace o Azure Active Directory najdete v README .

Můžete například použít DefaultAzureCredential k vytvoření klienta, který se ověří pomocí Azure Active Directory:

const { EventGridPublisherClient } = require("@azure/eventgrid");
const { DefaultAzureCredential } = require("@azure/identity");

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

Klíčové koncepty

EventGridPublisherClient

EventGridPublisherClient se používá k odesílání událostí do tématu event Gridu nebo do domény Event Gridu.

Schémata událostí

Event Grid podporuje více schémat pro kódování událostí. Při vytvoření vlastního tématu nebo domény zadáte schéma, které se použije při publikování událostí. I když můžete své téma nakonfigurovat tak, aby používalo vlastní schéma je častější používat již definované schématu Event Gridu nebo schématu CloudEvents 1.0. CloudEvents je projekt Cloud Native Computing Foundation, který vytváří specifikaci pro popis dat událostí běžným způsobem. Při vytváření EventGridPublisherClient musíte určit, které schéma je vaše téma nakonfigurováno pro použití:

Pokud je vaše téma nakonfigurované tak, aby používalo schéma Event Gridu, nastavte "EventGrid" jako typ schématu:

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

Pokud je vaše téma nakonfigurované tak, aby používalo schéma událostí cloudu, nastavte cloudEvent jako typ schématu:

const client = new EventGridPublisherClient(
  "<endpoint>",
  "CloudEvent",
  new AzureKeyCredential("<API Key>")
);

Pokud je vaše téma nakonfigurované tak, aby používalo vlastní schéma událostí, nastavte jako typ schématu "Vlastní":

const client = new EventGridPublisherClient(
  "<endpoint>",
  "Custom",
  new AzureKeyCredential("<API Key>")
);

Vytvoření klienta s jiným schématem, než jaké je téma nakonfigurované tak, aby očekávalo, způsobí chybu ze služby a vaše události nebudou publikovány.

Pomocí fragmentu kódu Azure CLI níže můžete zjistit, jaké vstupní schéma se pro téma Event Gridu nakonfigurovalo:

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

EventGridDeserializer

Události doručované příjemcům službou Event Grid se doručují jako JSON. Služba Event Grid může v závislosti na typu příjemce doručovat jednu nebo více událostí jako součást jedné datové části. I když tyto události mohou být deserializovány pomocí normálních javascriptových metod, jako je JSON.parse, tato knihovna nabízí pomocný typ pro deserializaci událostí, které se nazývají EventGridDeserializer.

Ve srovnání s použitím JSON.parse přímo EventGridDeserializer provede některé další převody při deserializaci událostí:

  1. EventGridDeserializer ověří, že jsou přítomny požadované vlastnosti události a že jsou správné typy.
  2. EventGridDeserializer převede vlastnost času události na javascriptový objekt Date.
  3. Při použití cloudových událostí lze binární data použít pro vlastnost dat události (pomocí Uint8Array). Když se událost odešle prostřednictvím Event Gridu, zakóduje se do base 64. EventGridDeserializer tato data dekóduje zpět do instance Uint8Array.
  4. Při deserilování systémové události (událost vygenerovaná jinou službou Azure) EventGridDeserializer provede další převody tak, aby objekt data odpovídal odpovídajícímu rozhraní, které popisuje jeho data. Při použití TypeScriptu tato rozhraní zajišťují silné psaní při přístupu k vlastnostem datového objektu pro systémovou událost.

Při vytváření instance EventGridDeserializer můžete zadat vlastní deserializery, které se používají k dalšímu převodu data objektu.

Distribuované trasování a cloudové události

Tato knihovna podporuje distribuované trasování pomocí @azure/core-tracing. Při použití distribuovaného trasování vytvoří tato knihovna rozsah během operace send. Kromě toho při odesílání událostí pomocí schématu Cloud Events 1.0 sada SDK přidá do událostí distribuovaná metadata trasování pomocí rozšíření Distribuované trasování. Hodnoty vlastností rozšíření traceparent a tracestate odpovídají hlavičce traceparent a tracestate z požadavku HTTP, který odesílá události. Pokud událost již má vlastnost rozšíření traceparent, není aktualizována.

Event Grid v Kubernetes

Tato knihovna byla testována a ověřena na Kubernetes pomocí služby Azure Arc.

Příklady

Publikování vlastní události do tématu Event Gridu pomocí schématu Event Gridu

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API key>")
);

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

Publikování vlastní události do tématu v doméně Event Gridu pomocí schématu Event Gridu

Publikování událostí do domény Event Gridu se podobá publikování do tématu Event Gridu s tím rozdílem, že při použití schématu Event Gridu pro události musíte zahrnout vlastnost topic. Při publikování událostí ve schématu Cloud Events 1.0 se požadovaná vlastnost source použije jako název tématu v doméně k publikování do:

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API key>")
);

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

Deserializace události

EventGridDeserializer lze použít k deserializaci událostí doručované službou Event Grid. V tomto příkladu máme cloudovou událost, která se deserializuje pomocí EventGridDeserializer a používá isSystemEvent k detekci typu událostí, které jsou.

const { EventGridDeserializer, isSystemEvent } = require("@azure/eventgrid");

async function main() {
  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");
  }
}

main();

Řešení problémů

Protokolování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete protokolování povolit za běhu voláním setLogLevel v @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Další kroky

Podrobné příklady použití této knihovny najdete v ukázkách adresáři.

Přispívající

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.

imprese