Bibliothèque cliente Azure Event Grid pour JavaScript - version 5.5.0
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
- Versions LTS de Node.js
- Dernières versions de Safari, Chrome, Edge et Firefox.
Pour plus d’informations, consultez notre politique de support .
Prérequis
- Un abonnement Azure.
- Une rubrique ou un domaine Event Grid existant. 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>
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 :
EventGridDeserializer
valide que les propriétés requises d’un événement sont présentes et sont les types appropriés.EventGridDeserializer
convertit la propriété de temps d’événement en objet JavaScriptDate
.- 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 deUint8Array
. - 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’objetdata
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.
Projets associés
Azure SDK for JavaScript
Commentaires
https://aka.ms/ContentUserFeedback.
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultezEnvoyer et afficher des commentaires pour