Partager via

Bibliothèque cliente Azure Event Grid pour JavaScript - version 5.5.0

  • Article

Azure Event Grid est un service basé sur le cloud qui fournit une distribution fiable d’événements à 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 un schéma personnalisé
  • Décoder et traiter les é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 :

Prise en main

Environnements actuellement pris en charge

Pour plus d’informations, consultez notre politique de support .

Prérequis

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>

Installez le package @azure/eventgrid

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

npm install @azure/eventgrid

Créez et authentifiez unEventGridPublisherClient

Pour créer un objet client afin d’accéder à l’API Event Grid, vous aurez besoin endpoint du 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 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’extrait de code Azure CLI ci-dessous :

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

Une fois que vous avez une clé API et un point de terminaison, vous pouvez utiliser la AzureKeyCredential classe 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 SAS permet d’accéder à l’envoi d’é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 SAS a un temps d’expération, auquel moment il n’est plus valide. Pour utiliser un jeton SAS pour l’authentification, utilisez le 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 generateSharedAccessSigniture fonction .

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 l’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 à des utilisateurs, des groupes ou des applications.

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

Avec le @azure/identity package, 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 LE@azure/identity FICHIER README.

Par exemple, l’utilisation peut utiliser DefaultAzureCredential pour construire un client qui s’authentifiera à 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é en envoyant des événements à une rubrique Event Grid ou à un domaine Event Grid.

Schémas d’événements

Event Grid prend en charge plusieurs schémas pour les événements d’encodage. Lors de la création d’une rubrique ou d’un domaine personnalisé, vous spécifiez le schéma qui sera utilisé lors de la publication d’événements. Bien que vous pouvez 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 le 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 d’une manière commune. Lorsque vous construisez EventGridPublisherClient, vous devez spécifier le schéma que votre rubrique est configurée pour 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 à quoi 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. En fonction du type de consommateur à qui la livraison est effectuée, le service Event Grid peut fournir un ou plusieurs événements dans le cadre d’une seule charge utile. Bien que ces événements puissent être désérialisés à l’aide de méthodes JavaScript normales telles que JSON.parse, cette bibliothèque offre un type d’assistance pour la désérialisation des événements, appelé EventGridDeserializer.

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

  1. EventGridDeserializer valide que les propriétés requises d’un événement sont présentes et sont les types appropriés.
  2. EventGridDeserializer convertit la propriété de temps d’événement en objet JavaScript Date .
  3. 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.
  4. Lors de la désériilisation d’un événement système (événement généré par un autre service Azure), EventGridDeserializer effectue des conversions supplémentaires afin que l’objet data corresponde à l’interface correspondante qui décrit ses données. Lorsque vous utilisez TypeScript, ces interfaces garantissent que vous disposez d’un type de frappe fort lorsque vous accédez 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 qui sont 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. Lors de l’utilisation du suivi distribué, cette bibliothèque crée une étendue pendant une send opération. En outre, lors de l’envoi d’événements à l’aide du schéma Cloud Events 1.0, le SDK ajoute des métadonnées de suivi distribué aux événements à l’aide de l’extension Suivi distribué. Les valeurs des propriétés de l’extension traceparent et tracestate correspondent aux traceparent en-têtes 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 , il n’est pas mis à 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 topic propriété . Lors de la publication d’événements dans le schéma Cloud Events 1.0, la propriété requise source est utilisée comme nom de la rubrique dans le domaine sur lequel publier :

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 peut être utilisé pour désérialiser des événements fournis par Event Grid. Dans cet exemple, nous avons un événement cloud qui est désérialisé à l’aide EventGridDeserializer de et utilisé isSystemEvent pour détecter le type d’événements qu’il s’agit.

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

Résolution des problèmes

Journalisation

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour avoir 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 @azure/logger :

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

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentation du package @azure/enregistreur d’événements.

Étapes suivantes

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

Contribution

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.

Impressions