Partager via

Azure Event Grid bibliothèque de client pour JavaScript - version 5.1.0-beta.1

  • Article

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 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 avez 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 pouvez trouver 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 disposez d’une clé API et d’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 SAS

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ériation, auquel cas 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 SAS à 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 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 à 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 LISEZ-MOI.

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é 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 des événements. 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. Même si 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 celui auquel la rubrique est configurée entraîne une erreur à partir 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 à qui vous êtes remis, 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 qu’il s’agit des types appropriés.
  2. EventGridDeserializer convertit la propriété d’heure 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 Uint8Arrayde ). Lorsque l’événement est envoyé via Event Grid, il est encodé en Base 64. EventGridDeserializerdécode ces données dans un instance de Uint8Array.
  4. Lors de la désérition 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 typage fort 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’un instance de EventGridDeserializer vous pouvez fournir des désérialiseurs personnalisés qui sont utilisés pour convertir davantage l’objetdata.

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 au cours d’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 De suivi distribué. Les valeurs des propriétés d’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é sur 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é sur 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 dans 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 les événements remis 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 sur le 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