Sdílet prostřednictvím

Azure Event Grid klientské knihovny pro JavaScript – verze 5.4.0

  • Článek

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

Klientská knihovna slouží k:

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

Klíčové odkazy:

Začínáme

Aktuálně podporovaná prostředí

  • LtS verze Node.js
  • Nejnovější verze prohlížečů Safari, Chrome, Edge a Firefox.

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 Služby Event Grid

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

Nainstalujte balíček @azure/eventgrid.

Nainstalujte klientskou knihovnu Azure Event Grid pro JavaScript pomocí npm:

npm install @azure/eventgrid

Vytvoření a ověření EventGridPublisherClient

Pokud chcete vytvořit objekt klienta pro přístup k rozhraní API služby Event Grid, budete potřebovat endpoint téma služby Event Grid a credentialobjekt . 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 pro téma Event Gridu 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 Event Gridu a načtěte přístupový klíč nebo použijte následující fragment kódu Azure CLI :

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

Jakmile budete mít klíč rozhraní API a koncový bod, můžete pomocí AzureKeyCredential třídy ověřit klienta 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íč i 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ý se dá použít až do jeho opětovného vygenerování, má token SAS dobu experace, kdy už není platný. Pokud chcete k ověřování použít token SAS, použijte AzureSASCredential následující příkaz:

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

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

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

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 s Azure Active Directory (Azure AD) pro ověřování požadavků na základě identity. S Azure AD můžete pomocí řízení přístupu na základě role (RBAC) udělit uživatelům, skupinám nebo aplikacím přístup k prostředkům Azure Event Grid.

Pokud chcete odesílat události do tématu nebo domény pomocí TokenCredential, musí 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 ve vývojovém i produkčním prostředí. Další informace o Službě Azure Active Directory najdete v @azure/identity tématu README.

Můžete například použít DefaultAzureCredential k vytvoření klienta, který se bude ověřovat 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 nakonfigurovat téma tak, aby používalo vlastní schéma , je častější použít již definované schéma Event Gridu nebo schéma CloudEvents 1.0. CloudEvents je projekt cloudových nativních výpočetních prostředků, který vytváří specifikaci pro běžné popisování dat událostí. Při vytváření EventGridPublisherClient musíte zadat schéma, které je vaše téma nakonfigurované pro použití:

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

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 jako typ schématu CloudEvent:

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

Sestavení klienta s jiným schématem, než které je v tématu nakonfigurováno, bude mít za následek chybu ze služby a vaše události nebudou publikovány.

Pomocí následujícího fragmentu kódu Azure CLI můžete zjistit, jaké vstupní schéma bylo nakonfigurováno pro téma Event Gridu:

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í běžných javascriptových metod, jako je JSON.parse, tato knihovna nabízí pomocný typ pro deserializaci událostí s názvem EventGridDeserializer.

V porovnání s přímým EventGridDeserializer použitím JSON.parse provádí některé další převody při deserializaci událostí:

  1. EventGridDeserializer ověřuje, že jsou k dispozici požadované vlastnosti události a že jsou správné typy.
  2. EventGridDeserializer převede vlastnost čas události na objekt JavaScriptu Date .
  3. Při použití cloudových událostí je možné binární data použít pro vlastnost dat události (pomocí Uint8Array). Když se událost odešle přes Event Grid, zakóduje se v base 64. EventGridDeserializerdekóduje tato data zpět na instanci .Uint8Array
  4. Při deserilizaci systémové události (události vygenerované jinou službou Azure) EventGridDeserializer provede další převody tak, aby data objekt 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 událost systému.

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

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 během send operace rozsah. Kromě toho sada SDK při odesílání událostí pomocí schématu Cloud Events 1.0 přidá do událostí distribuovaná metadata trasování pomocí rozšíření Distribuované trasování. Hodnoty vlastností traceparent rozšíření a tracestate odpovídají traceparent hlavičce a tracestate z požadavku HTTP, který odesílá události. Pokud už událost má traceparent vlastnost rozšíření, neaktualizuje se.

Event Grid v Kubernetes

Tato knihovna byla testována a ověřena v Kubernetes pomocí 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ě Služby Event Grid pomocí schématu Event Gridu

Publikování událostí do domény Event Gridu je podobné 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 topic vlastnost. Při publikování událostí ve schématu Cloud Events 1.0 se jako název tématu v doméně pro publikování používá požadovaná source vlastnost:

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 událost cloudu, která se deserializuje pomocí EventGridDeserializer a používá isSystemEvent se ke zjištění typu událostí.

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

Poradce při potížích

protokolování

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné 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 balíčkům @azure/protokolovacího nástroje.

Další kroky

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

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si prosím průvodce přispívání , kde se dozvíte více o tom, jak sestavit a otestovat kód.

Imprese