Freigeben über

Azure Event Grid Clientbibliothek für JavaScript– Version 5.1.0-beta.1

  • Artikel

Azure Event Grid ist ein cloudbasierter Dienst, der eine zuverlässige Ereignisbereitstellung in großem Umfang ermöglicht.

Verwenden Sie die Clientbibliothek für folgende Aktionen:

  • Senden von Ereignissen an Event Grid mithilfe von Event Grid, Cloud Events 1.0-Schemas oder einem benutzerdefinierten Schema
  • Decodieren und Verarbeiten von Ereignissen, die an einen Event Grid-Handler übermittelt wurden
  • Generieren von Shared Access Signatures für Event Grid-Themen

Wichtige Links:

Erste Schritte

Die derzeitig unterstützten Umgebungen

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

Wenn Sie die Azure CLI verwenden, ersetzen <your-resource-group-name> Sie und <your-resource-name> durch Ihre eigenen eindeutigen Namen:

Erstellen eines Event Grid-Themas

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

Erstellen einer Event Grid-Domäne

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

Installieren Sie das Paket @azure/eventgrid.

Installieren Sie die Azure Event Grid-Clientbibliothek für JavaScript mit npm:

npm install @azure/eventgrid

Erstellen und Authentifizieren eines EventGridPublisherClient

Um ein Clientobjekt für den Zugriff auf die Event Grid-API zu erstellen, benötigen Sie die endpoint ihres Event Grid-Themas und eine credential. Der Event Grid-Client kann entweder einen Zugriffsschlüssel oder eine Sas (Shared Access Signature) verwenden, die aus einem Zugriffsschlüssel erstellt wurde.

Sie finden den Endpunkt für Ihr Event Grid-Thema entweder im Azure-Portal oder mithilfe des folgenden Azure CLI-Ausschnitts :

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

Verwenden eines Zugriffsschlüssels

Verwenden Sie das Azure-Portal , um zu Ihrer Event Grid-Ressource zu navigieren und einen Zugriffsschlüssel abzurufen, oder verwenden Sie den folgenden Azure CLI-Codeausschnitt :

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

Sobald Sie über einen API-Schlüssel und einen Endpunkt verfügen, können Sie die AzureKeyCredential -Klasse verwenden, um den Client wie folgt zu authentifizieren:

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

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

Verwenden eines SAS-Tokens

Wie ein Zugriffsschlüssel ermöglicht ein SAS-Token den Zugriff auf das Senden von Ereignissen an ein Event Grid-Thema. Im Gegensatz zu einem Zugriffsschlüssel, der verwendet werden kann, bis er neu generiert wird, verfügt ein SAS-Token über eine Experationszeit, sodass es nicht mehr gültig ist. Verwenden Sie wie folgt, um ein SAS-Token für die AzureSASCredential Authentifizierung zu verwenden:

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

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

Sie können mithilfe der generateSharedAccessSigniture -Funktion ein SAS-Token generieren.

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

Verwenden von Azure Active Directory (AAD)

Azure EventGrid bietet die Integration in Azure Active Directory (Azure AD) für die identitätsbasierte Authentifizierung von Anforderungen. Mit Azure AD können Sie die rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) verwenden, um Benutzern, Gruppen oder Anwendungen Zugriff auf Ihre Azure Event Grid-Ressourcen zu gewähren.

Um Ereignisse mit einem an ein Thema oder eine TokenCredentialDomäne zu senden, muss der authentifizierten Identität die Rolle "EventGrid-Datensender" zugewiesen sein.

Mit dem @azure/identity Paket können Sie Anforderungen nahtlos in Entwicklungs- und Produktionsumgebungen autorisieren. Weitere Informationen zu Azure Active Directory finden Sie in der @azure/identity Infodatei.

Mithilfe von kann DefaultAzureCredential beispielsweise ein Client erstellt werden, der sich mithilfe von Azure Active Directory authentifiziert:

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

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

Wichtige Begriffe

EventGridPublisherClient

EventGridPublisherClient wird verwendet, um Ereignisse an ein Event Grid-Thema oder eine Event Grid-Domäne zu senden.

Ereignisschemas

Event Grid unterstützt mehrere Schemas für die Codierung von Ereignissen. Wenn ein benutzerdefiniertes Thema oder eine domäne erstellt wird, geben Sie das Schema an, das beim Veröffentlichen von Ereignissen verwendet wird. Sie können Ihr Thema zwar für die Verwendung eines benutzerdefinierten Schemas konfigurieren, es ist jedoch üblicher, das bereits definierte Event Grid - oder CloudEvents 1.0-Schema zu verwenden. CloudEvents ist ein Cloud Native Computing Foundation-Projekt, das eine Spezifikation für die allgemeine Beschreibung von Ereignisdaten erstellt. Wenn Sie den EventGridPublisherClient erstellen, müssen Sie angeben, für welches Schema Ihr Thema konfiguriert ist:

Wenn Ihr Thema für die Verwendung des Event Grid-Schemas konfiguriert ist, legen Sie "EventGrid" als Schematyp fest:

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

Wenn Ihr Thema für die Verwendung des Cloudereignisschemas konfiguriert ist, legen Sie "CloudEvent" als Schematyp fest:

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

Wenn Ihr Thema für die Verwendung eines benutzerdefinierten Ereignisschemas konfiguriert ist, legen Sie "Benutzerdefiniert" als Schematyp fest:

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

Das Erstellen des Clients mit einem anderen Schema als das, was das Thema erwartet, führt zu einem Fehler des Diensts, und Ihre Ereignisse werden nicht veröffentlicht.

Sie können sehen, welches Eingabeschema für ein Event Grid-Thema konfiguriert wurde, indem Sie den folgenden Azure CLI-Codeausschnitt verwenden:

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

EventGridDeserializer

Ereignisse, die von Event Grid an Consumer übermittelt werden, werden als JSON bereitgestellt. Abhängig vom Typ des Consumers, an den geliefert wird, kann der Event Grid-Dienst ein oder mehrere Ereignisse als Teil einer einzelnen Nutzlast bereitstellen. Diese Ereignisse können zwar mit normalen JavaScript-Methoden wie JSON.parsedeserialisiert werden, aber diese Bibliothek bietet einen Hilfstyp für die Deserialisierung von Ereignissen mit dem Namen EventGridDeserializer.

Im Vergleich zur direkten Verwendung JSON.parse werden einige zusätzliche Konvertierungen durchgeführt, EventGridDeserializer während Deserializng-Ereignisse ausgeführt werden:

  1. EventGridDeserializer überprüft, ob die erforderlichen Eigenschaften eines Ereignisses vorhanden sind und die richtigen Typen sind.
  2. EventGridDeserializer konvertiert die Ereigniszeiteigenschaft in ein JavaScript-Objekt Date .
  3. Bei Verwendung von Cloudereignissen können Binärdaten für die Dateneigenschaft eines Ereignisses verwendet werden (mithilfe Uint8Arrayvon ). Wenn das Ereignis über Event Grid gesendet wird, wird es in Base 64 codiert. EventGridDeserializerdecodiert diese Daten wieder in eine instance von Uint8Array.
  4. Beim Deserilisieren eines Systemereignisses (ein von einem anderen Azure-Dienst generiertes Ereignis) EventGridDeserializer werden zusätzliche Konvertierungen durchgeführt, damit das data Objekt mit der entsprechenden Schnittstelle übereinstimmt, die seine Daten beschreibt. Bei Verwendung von TypeScript stellen diese Schnittstellen sicher, dass Sie beim Zugriff auf Eigenschaften des Datenobjekts für ein Systemereignis über eine starke Eingabe verfügen.

Wenn Sie eine instance können EventGridDeserializer Sie benutzerdefinierte Deserialisierer bereitstellen, die zum weiteren Konvertieren des data Objekts verwendet werden.

Verteilte Ablaufverfolgung und Cloudereignisse

Diese Bibliothek unterstützt die verteilte Ablaufverfolgung mit @azure/core-tracing. Bei Verwendung der verteilten Ablaufverfolgung erstellt diese Bibliothek während eines Vorgangs eine send Spanne. Darüber hinaus fügt das SDK beim Senden von Ereignissen mithilfe des Cloud Events 1.0-Schemas verteilte Ablaufverfolgungsmetadaten zu den Ereignissen mithilfe der Erweiterung Für verteilte Ablaufverfolgung hinzu. Die Werte für die Erweiterungseigenschaften traceparent und tracestate entsprechen den traceparent Headern und tracestate aus der HTTP-Anforderung, die die Ereignisse sendet. Wenn ein Ereignis bereits über eine Erweiterungseigenschaft traceparent verfügt, wird es nicht aktualisiert.

Event Grid in Kubernetes

Diese Bibliothek wurde in Kubernetes mithilfe von Azure Arc getestet und überprüft.

Beispiele

Veröffentlichen eines benutzerdefinierten Ereignisses in einem Event Grid-Thema mithilfe des Event Grid-Schemas

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",
    },
  },
]);

Veröffentlichen eines benutzerdefinierten Ereignisses in einem Thema in einer Event Grid-Domäne mithilfe des Event Grid-Schemas

Das Veröffentlichen von Ereignissen in einer Event Grid-Domäne ähnelt der Veröffentlichung in einem Event Grid-Thema, mit der Ausnahme, dass Sie bei Verwendung des Event Grid-Schemas für Ereignisse die topic -Eigenschaft einschließen müssen. Beim Veröffentlichen von Ereignissen im Cloud Events 1.0-Schema wird die erforderliche source Eigenschaft als Name des Themas in der Domäne verwendet, in der veröffentlicht werden soll:

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",
    },
  },
]);

Deserialisieren eines Ereignisses

EventGridDeserializer kann verwendet werden, um von Event Grid bereitgestellte Ereignisse zu deserialisieren. In diesem Beispiel haben wir ein Cloudereignis, das mithilfe von EventGridDeserializer und isSystemEvent deserialisiert wird, um zu erkennen, um welche Art von Ereignissen es sich handelt.

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

Problembehandlung

Protokollierung

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren der Protokolle finden Sie in der Dokumentation zu @azure-/Protokollierungspaketen.

Nächste Schritte

Ausführliche Beispiele zur Verwendung dieser Bibliothek finden Sie im Beispielverzeichnis .

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Aufrufe