Freigeben über

Azure Event Grid-Clientbibliothek für JavaScript – Version 5.9.0

  • Artikel

Azure Event Grid ist ein cloudbasierter Dienst, der eine zuverlässige Ereignisbereitstellung im großen Maßstab bietet.

Verwenden Sie die Clientbibliothek für Folgendes:

  • Senden von Ereignissen an das Ereignisraster mithilfe des Ereignisrasters, der Cloudereignisse 1.0-Schemas oder eines benutzerdefinierten Schemas
  • Decodieren und Verarbeiten von Ereignissen, die an einen Ereignisrasterhandler übermittelt wurden
  • Generieren freigegebener Zugriffssignaturen für Ereignisrasterthemen

Wichtige Links:

Erste Schritte

Derzeit unterstützte Umgebungen

Weitere Informationen finden Sie in unserer Supportrichtlinie.

Voraussetzungen

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

Erstellen eines Ereignisrasterthemas

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

Erstellen einer Ereignisrasterdomäne

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

Installieren des @azure/eventgrid-Pakets

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

npm install @azure/eventgrid

Erstellen und Authentifizieren einer EventGridPublisherClient

Um ein Clientobjekt für den Zugriff auf die Event Grid-API zu erstellen, benötigen Sie die endpoint Ihres Ereignisrasterthemas und ein credential. Der Ereignisrasterclient kann entweder einen Zugriffsschlüssel oder eine FREIGEGEBENe Zugriffssignatur (Shared Access Signature, SAS) verwenden, die über einen Zugriffsschlüssel erstellt wurde.

Sie finden den Endpunkt für Ihr Ereignisrasterthema entweder im Azure Portal oder mithilfe des folgenden Azure CLI Codeausschnitts:

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

Verwenden einer Zugriffstaste

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>

Nachdem 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 bei einem Zugriffsschlüssel ermöglicht ein SAS-Token den Zugriff auf das Senden von Ereignissen an ein Ereignisrasterthema. Im Gegensatz zu einem Zugriffsschlüssel, der verwendet werden kann, bis er neu generiert wird, verfügt ein SAS-Token über eine Experationszeit, an der es an diesem Punkt nicht mehr gültig ist. Um ein SAS-Token für die Authentifizierung zu verwenden, verwenden Sie die AzureSASCredential wie folgt:

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

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

Sie können ein SAS-Token mithilfe der generateSharedAccessSigniture-Funktion 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 Integration in Azure Active Directory (Azure AD) für die identitätsbasierte Authentifizierung von Anforderungen. Mit Azure AD können Sie rollenbasierte Zugriffssteuerung (RBAC) verwenden, um Benutzern, Gruppen oder Anwendungen Zugriff auf Ihre Azure Event Grid-Ressourcen zu gewähren.

Zum Senden von Ereignissen an ein Thema oder eine Domäne mit einem TokenCredentialsollte die authentifizierte Identität die Rolle "EventGrid Data Sender" zugewiesen haben.

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

Verwenden Sie z. B. DefaultAzureCredential, um einen Client zu erstellen, der sich mit Azure Active Directory authentifiziert:

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

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

Schlüsselkonzepte

EventGridPublisherClient

EventGridPublisherClient wird verwendet, um Ereignisse an ein Ereignisrasterthema oder eine Ereignisrasterdomäne zu senden.

Ereignisschemas

Das Ereignisraster unterstützt mehrere Schemas für Codierungsereignisse. 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 so konfigurieren, dass ein benutzerdefiniertes Schema verwendet wird, es üblicher ist, das bereits definierte Ereignisrasterschema oder CloudEvents 1.0-Schema-zu verwenden. CloudEvents ist ein Cloud Native Computing Foundation-Projekt, das eine Spezifikation zur gemeinsamen Beschreibung von Ereignisdaten erzeugt. Wenn Sie den EventGridPublisherClient erstellen, müssen Sie angeben, welches Schema ihr Thema für die Verwendung konfiguriert ist:

Wenn Ihr Thema für die Verwendung des Ereignisrasterschemas 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 Cloud-Ereignisschemas 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 dem, was das zu erwartende Thema konfiguriert ist, führt zu einem Fehler vom Dienst, und Ihre Ereignisse werden nicht veröffentlicht.

Sie können sehen, welches Eingabeschema für ein Ereignisrasterthema konfiguriert wurde, indem Sie den folgenden codeausschnitt Azure CLI 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 übermittelt. Abhängig vom Typ des Verbrauchers, an den der Dienst übermittelt wird, kann der Event Grid-Dienst ein oder mehrere Ereignisse als Teil einer einzelnen Nutzlast bereitstellen. Während diese Ereignisse mit normalen JavaScript-Methoden wie JSON.parsedeserialisiert werden können, bietet diese Bibliothek einen Hilfstyp für Deserialisierungsereignisse, die als EventGridDeserializerbezeichnet werden.

Im Vergleich zur direkten Verwendung von JSON.parse führt EventGridDeserializer während deserializng-Ereignisses einige zusätzliche Konvertierungen durch:

  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-Date-Objekt.
  3. Bei Verwendung von Cloudereignissen können Binärdaten für die Dateneigenschaft eines Ereignisses (mithilfe von Uint8Array) verwendet werden. Wenn das Ereignis über das Ereignisraster gesendet wird, wird es in Base 64 codiert. EventGridDeserializer decodieren diese Daten wieder in eine Instanz von Uint8Array.
  4. Beim Deserilisieren eines Systemereignis- (einem Ereignis, das von einem anderen Azure-Dienst generiert wird), führt EventGridDeserializer zusätzliche Konvertierungen durch, sodass das data-Objekt der entsprechenden Schnittstelle entspricht, die seine Daten beschreibt. Bei Verwendung von TypeScript stellen diese Schnittstellen sicher, dass Sie starke Eingaben haben, wenn Sie auf Eigenschaften des Datenobjekts für ein Systemereignis zugreifen.

Beim Erstellen einer Instanz von EventGridDeserializer können Sie benutzerdefinierte Deserializer bereitstellen, die zum weiteren Konvertieren des data-Objekts verwendet werden.

Verteilte Ablaufverfolgung und Cloudereignisse

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

Ereignisraster auf Kubernetes

Diese Bibliothek wurde mit Azure Arcauf Kubernetes getestet und überprüft.

Beispiele

Veröffentlichen eines benutzerdefinierten Ereignisses in einem Ereignisrasterthema mithilfe des Ereignisrasterschemas

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 Ereignisrasterdomäne mithilfe des Ereignisrasterschemas

Das Veröffentlichen von Ereignissen in einer Ereignisrasterdomäne ähnelt der Veröffentlichung in einem Ereignisrasterthema, mit der Ausnahme, dass Sie bei Verwendung des Ereignisrasterschemas für Ereignisse die eigenschaft topic 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 dem 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 können zum Deserialisieren von Ereignissen verwendet werden, die von Event Grid bereitgestellt werden. In diesem Beispiel haben wir ein Cloudereignis, das mithilfe von EventGridDeserializer deserialisiert wird, und isSystemEvent verwenden, um zu erkennen, welche Art von Ereignissen sie sind.

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

Fehlerbehebung

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren der Protokolle finden Sie in den @azure/Logger-Paketdokumenten.

Nächste Schritte

Ausführliche Beispiele zur Verwendung dieser Bibliothek finden Sie in den Beispielen Verzeichnis.

Beitragend

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.

Aufrufe