Bibliothèque de client Azure Event Grid pour JavaScript - version 5.5.1

Article
07/17/2024

Azure Event Grid est un service cloud qui fournit une livraison d’événements fiable à grande échelle.

Utilisez la bibliothèque cliente pour :

Envoyer des événements à Event Grid à l’aide des schémas Event Grid, Cloud Events 1.0 ou personnalisés
Décoder et traiter des événements qui ont été remis à un gestionnaire Event Grid
Générer des signatures d’accès partagé pour les rubriques Event Grid

Liens clés :

code source
package (NPM)
Documentation de référence de l’API
documentation produit
Exemples

Commencer

Environnements actuellement pris en charge

versions LTS de Node.js
Dernières versions de Safari, Chrome, Edge et Firefox.

Pour plus d’informations, consultez notre de stratégie de support .

Conditions préalables

Un abonnement Azure .
Rubrique ou domaine event Grid existant Event Grid. Si vous devez créer la ressource, vous pouvez utiliser le portail Azure ou azure CLI.

Si vous utilisez Azure CLI, remplacez <your-resource-group-name> et <your-resource-name> par vos propres noms uniques :

Créer une rubrique Event Grid

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

Créer un domaine Event Grid

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

Installer le package `@azure/eventgrid`

Installez la bibliothèque de client Azure Event Grid pour JavaScript avec npm:

npm install @azure/eventgrid

Créer et authentifier un `EventGridPublisherClient`

Pour créer un objet client pour accéder à l’API Event Grid, vous aurez besoin des endpoint de votre rubrique Event Grid et d’un credential. Le client Event Grid peut utiliser une clé d’accès ou une signature d’accès partagé (SAP) créée à partir d’une clé d’accès.

Vous trouverez le point de terminaison de votre rubrique Event Grid dans le du portail Azure ou à l’aide de l’extrait de code Azure CLI ci-dessous :

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

Utilisation d’une clé d’accès

Utilisez le portail Azure pour accéder à votre ressource Event Grid et récupérer une clé d’accès, ou utilisez l'azure CLI extrait de code ci-dessous :

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

Une fois que vous disposez d’une clé API et d’un point de terminaison, vous pouvez utiliser la classe AzureKeyCredential pour authentifier le client comme suit :

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

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

Utilisation d’un jeton SAP

Comme une clé d’accès, un jeton SAP permet d’envoyer des événements à une rubrique Event Grid. Contrairement à une clé d’accès, qui peut être utilisée jusqu’à ce qu’elle soit régénérée, un jeton SAP a un temps d’expération, à quel moment il n’est plus valide. Pour utiliser un jeton SAP pour l’authentification, utilisez la AzureSASCredential comme suit :

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

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

Vous pouvez générer un jeton SAP à l’aide de la fonction 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")
);

Utilisation d’Azure Active Directory (AAD)

Azure EventGrid fournit une intégration à Azure Active Directory (Azure AD) pour l’authentification basée sur l’identité des demandes. Avec Azure AD, vous pouvez utiliser le contrôle d’accès en fonction du rôle (RBAC) pour accorder l’accès à vos ressources Azure Event Grid aux utilisateurs, groupes ou applications.

Pour envoyer des événements à une rubrique ou un domaine avec un TokenCredential, l’identité authentifiée doit avoir le rôle « Expéditeur de données EventGrid » attribué.

Avec le package @azure/identity, vous pouvez autoriser en toute transparence les demandes dans les environnements de développement et de production. Pour en savoir plus sur Azure Active Directory, consultez la @azure/identity README.

Par exemple, l’utilisation peut utiliser DefaultAzureCredential pour construire un client qui s’authentifie à l’aide d’Azure Active Directory :

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

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

Concepts clés

EventGridPublisherClient

EventGridPublisherClient est utilisé pour envoyer des événements à une rubrique Event Grid ou à un domaine Event Grid.

Schémas d’événement

Event Grid prend en charge plusieurs schémas pour l’encodage d’événements. Quand une rubrique ou un domaine personnalisé est créé, vous spécifiez le schéma qui sera utilisé lors de la publication d’événements. Bien que vous puissiez configurer votre rubrique pour utiliser un schéma personnalisé il est plus courant d’utiliser le schéma Event Grid déjà défini ou schéma CloudEvents 1.0. CloudEvents est un projet Cloud Native Computing Foundation qui produit une spécification pour décrire les données d’événement de manière courante. Lorsque vous construisez EventGridPublisherClient, vous devez spécifier le schéma que votre rubrique est configuré pour l’utiliser :

Si votre rubrique est configurée pour utiliser le schéma Event Grid, définissez « EventGrid » comme type de schéma :

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

Si votre rubrique est configurée pour utiliser le schéma d’événement cloud, définissez « CloudEvent » comme type de schéma :

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

Si votre rubrique est configurée pour utiliser un schéma d’événement personnalisé, définissez « Personnalisé » comme type de schéma :

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

La construction du client avec un schéma différent de ce que la rubrique est configurée entraîne une erreur du service et vos événements ne seront pas publiés.

Vous pouvez voir quel schéma d’entrée a été configuré pour une rubrique Event Grid à l’aide de l’extrait de code Azure CLI ci-dessous :

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

EventGridDeserializer

Les événements remis aux consommateurs par Event Grid sont remis au format JSON. Selon le type de consommateur à remettre, le service Event Grid peut fournir un ou plusieurs événements dans le cadre d’une charge utile unique. Bien que ces événements puissent être désérialisés à l’aide de méthodes JavaScript normales comme JSON.parse, cette bibliothèque offre un type d’assistance pour désérialiser des événements, appelé EventGridDeserializer.

Par rapport à l’utilisation de JSON.parse directement, EventGridDeserializer effectue des conversions supplémentaires lors de la désérialisation des événements :

EventGridDeserializer vérifie que les propriétés requises d’un événement sont présentes et sont les bons types.
EventGridDeserializer convertit la propriété d’heure d’événement en objet Date JavaScript.
Lors de l’utilisation d’événements cloud, les données binaires peuvent être utilisées pour la propriété de données d’un événement (à l’aide de Uint8Array). Lorsque l’événement est envoyé via Event Grid, il est encodé en Base 64. EventGridDeserializer décodera ces données dans une instance de Uint8Array.
Lors de la désérialisation d’un d’événements système (événement généré par un autre service Azure), effectuez des conversions supplémentaires afin que l’objet corresponde à l’interface correspondante qui décrit ses données. Lorsque vous utilisez TypeScript, ces interfaces garantissent une saisie forte lors de l’accès aux propriétés de l’objet de données pour un événement système.

Lors de la création d’une instance de EventGridDeserializer vous pouvez fournir des désérialiseurs personnalisés utilisés pour convertir davantage l’objet data.

Suivi distribué et événements cloud

Cette bibliothèque prend en charge le suivi distribué à l’aide de @azure/core-tracing. Lorsque vous utilisez le suivi distribué, cette bibliothèque crée une étendue pendant une opération de send. En outre, lors de l’envoi d’événements à l’aide du schéma Cloud Events 1.0, le Kit de développement logiciel (SDK) ajoute des métadonnées de suivi distribué aux événements à l’aide de l’extension de suivi distribué . Les valeurs des propriétés d’extension traceparent et tracestate correspondent aux en-têtes traceparent et tracestate de la requête HTTP qui envoie les événements. Si un événement a déjà une propriété d’extension traceparent qu’elle n’est pas mise à jour.

Event Grid sur Kubernetes

Cette bibliothèque a été testée et validée sur Kubernetes à l’aide d’Azure Arc.

Exemples

Publier un événement personnalisé dans une rubrique Event Grid à l’aide du schéma Event Grid

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

Publier un événement personnalisé dans une rubrique dans un domaine Event Grid à l’aide du schéma Event Grid

La publication d’événements dans un domaine Event Grid est similaire à la publication dans une rubrique Event Grid, sauf que lorsque vous utilisez le schéma Event Grid pour les événements, vous devez inclure la propriété topic. Lors de la publication d’événements dans le schéma Cloud Events 1.0, la propriété source requise est utilisée comme nom de la rubrique dans le domaine à publier sur :

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

Désérialisation d’un événement

EventGridDeserializer pouvez être utilisé pour désérialiser les événements remis par Event Grid. Dans cet exemple, nous avons un événement cloud désérialisé à l’aide de EventGridDeserializer et nous utilisons isSystemEvent pour détecter le type d’événements qu’ils sont.

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

Dépannage

Exploitation forestière

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux d’activité, vous pouvez consulter les documents de package @azure/enregistreur d’événements.

Étapes suivantes

Consultez les exemples répertoire pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque.

Contribuant

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Kit de développement logiciel (SDK) Microsoft Azure pour JavaScript

Impressions

Partager via

Bibliothèque de client Azure Event Grid pour JavaScript - version 5.5.1

Commencer

Environnements actuellement pris en charge

Conditions préalables

Créer une rubrique Event Grid

Créer un domaine Event Grid

Installer le package `@azure/eventgrid`

Créer et authentifier un `EventGridPublisherClient`

Utilisation d’une clé d’accès

Utilisation d’un jeton SAP

Utilisation d’Azure Active Directory (AAD)

Concepts clés

EventGridPublisherClient

Schémas d’événement

EventGridDeserializer

Suivi distribué et événements cloud

Event Grid sur Kubernetes

Exemples

Publier un événement personnalisé dans une rubrique Event Grid à l’aide du schéma Event Grid

Publier un événement personnalisé dans une rubrique dans un domaine Event Grid à l’aide du schéma Event Grid

Désérialisation d’un événement

Dépannage

Exploitation forestière

Étapes suivantes

Contribuant

Ressources supplémentaires

Partager via

Bibliothèque de client Azure Event Grid pour JavaScript - version 5.5.1

Commencer

Environnements actuellement pris en charge

Conditions préalables

Créer une rubrique Event Grid

Créer un domaine Event Grid

Installer le package @azure/eventgrid

Créer et authentifier un EventGridPublisherClient

Utilisation d’une clé d’accès

Utilisation d’un jeton SAP

Utilisation d’Azure Active Directory (AAD)

Concepts clés

EventGridPublisherClient

Schémas d’événement

EventGridDeserializer

Suivi distribué et événements cloud

Event Grid sur Kubernetes

Exemples

Publier un événement personnalisé dans une rubrique Event Grid à l’aide du schéma Event Grid

Publier un événement personnalisé dans une rubrique dans un domaine Event Grid à l’aide du schéma Event Grid

Désérialisation d’un événement

Dépannage

Exploitation forestière

Étapes suivantes

Contribuant

Projets connexes

Ressources supplémentaires

Installer le package `@azure/eventgrid`

Créer et authentifier un `EventGridPublisherClient`