Share via

Azure Event Grid klientské knihovny pro JavaScript – verze 5.1.0-beta.1

  • Článek

Azure Event Grid je cloudová služba, která poskytuje spolehlivé doručování událostí v masivní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 obslužné rutině Event Gridu
  • 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 Event Gridu

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 event gridu endpoint , budete potřebovat téma Event Gridu credentiala . 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ý je možné použít, dokud není znovu vygenerován, má token SAS dobu prodlevy, kdy už není platný. Pokud chcete k ověřování použít token SAS, použijte AzureSASCredential následující:

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 se službou Azure Active Directory (Azure AD) pro ověřování požadavků na základě identit. 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éně pomocí TokenCredential, musí mít ověřená identita přiřazenou roli EventGrid Data Sender.

@azure/identity Balíček umožňuje bezproblémovou autorizaci požadavků ve vývojovém i produkčním prostředí. Další informace o Azure Active Directory najdete v souboru @azure/identity 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 vytváření vlastního tématu nebo domény určíte schéma, které se použije při publikování událostí. I když můžete téma nakonfigurovat tak, aby používalo vlastní schéma , běžnější je použití již definovaného schématu Event Gridu nebo schématu CloudEvents 1.0. CloudEvents je projekt základu nativního výpočetního prostředí pro cloud, který vytváří specifikaci pro popis dat událostí běžným způsobem. Při vytváření třídy EventGridPublisherClient musíte určit schéma, které je pro vaše téma nakonfigurované:

Pokud je 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 cloudové události, nastavte jako typ schématu CloudEvent:

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

Pokud je 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ž je nakonfigurováno pro očekávané očekávané téma, způsobí chybu ze služby a vaše události nebudou publikovány.

Pomocí fragmentu kódu Azure CLI níže zjistíte, 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í ve formátu JSON. V závislosti na typu příjemce, který se doručuje, může služba Event Grid 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, jestli jsou k dispozici požadované vlastnosti události a že jsou správné typy.
  2. EventGridDeserializer převede vlastnost času události na objekt jazyka JavaScript Date .
  3. Při použití cloudových událostí je možné pro vlastnost dat události použít binární data (pomocí ).Uint8Array Když se událost odešle prostřednictvím Event Gridu, zakóduje se do base 64. EventGridDeserializer dekó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éry, 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 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ě 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 topic vlastnost . Při publikování událostí ve schématu cloudových událostí 1.0 se požadovaná source vlastnost používá jako název tématu v doméně, do které se má publikovat:

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í.

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 ukázek .

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete další informace o tom, jak sestavit a otestovat kód.

Imprese