Biblioteca cliente de Azure Event Grid para JavaScript: versión 5.10.0
azure Event Grid es un servicio basado en la nube que proporciona entrega de eventos confiable a gran escala.
Use la biblioteca cliente para:
- Envío de eventos a Event Grid mediante los esquemas de Event Grid, Cloud Events 1.0 o un esquema personalizado
- Descodificar y procesar eventos que se entregaron a un controlador de Event Grid
- Generación de firmas de acceso compartido para temas de Event Grid
Vínculos clave:
- código fuente
- paquete de
(NPM) - documentación de referencia de api de
- documentación del producto de
- Ejemplos
Empezar
Entornos admitidos actualmente
- versiones ltS de Node.js
- Versiones más recientes de Safari, Chrome, Edge y Firefox.
Consulte nuestra de directiva de soporte técnico de
Prerrequisitos
- Una suscripción de Azure .
- Un tema o dominio de Event Grid existente. Si necesita crear el recurso, puede usar el azure Portal o cli de Azure.
Si usa la CLI de Azure, reemplace <your-resource-group-name> y <your-resource-name> por sus propios nombres únicos:
Creación de un tema de Event Grid
az eventgrid topic create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>
Creación de un dominio de Event Grid
az eventgrid domain create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>
Instalación del paquete @azure/eventgrid
Instale la biblioteca cliente de Azure Event Grid para JavaScript con npm:
npm install @azure/eventgrid
Creación y autenticación de un EventGridPublisherClient
Para crear un objeto de cliente para acceder a Event Grid API, necesitará el endpoint del tema de Event Grid y un credential. El cliente de Event Grid puede usar una clave de acceso o una firma de acceso compartido (SAS) creada a partir de una clave de acceso.
Puede encontrar el punto de conexión del tema de Event Grid en el de Azure Portal de
az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"
Uso de una clave de acceso
Use el de Azure Portal de
az eventgrid topic key list --resource-group <your-resource-group-name> --name <your-event-grid-topic-name>
Una vez que tenga una clave de API y un punto de conexión, puede usar la clase AzureKeyCredential para autenticar el cliente de la siguiente manera:
const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");
const client = new EventGridPublisherClient(
"<endpoint>",
"<endpoint schema>",
new AzureKeyCredential("<Access Key>"),
);
Uso de un token de SAS
Al igual que una clave de acceso, un token de SAS permite el acceso a enviar eventos a un tema de Event Grid. A diferencia de una clave de acceso, que se puede usar hasta que se vuelve a generar, un token de SAS tiene un tiempo de experación, en cuyo momento ya no es válido. Para usar un token de SAS para la autenticación, use el AzureSASCredential como se indica a continuación:
const { EventGridPublisherClient, AzureSASCredential } = require("@azure/eventgrid");
const client = new EventGridPublisherClient(
"<endpoint>",
"<endpoint schema>",
new AzureSASCredential("<SAS Token>"),
);
Puede generar un token de SAS mediante la función 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"),
);
Uso de Azure Active Directory (AAD)
Azure EventGrid proporciona integración con Azure Active Directory (Azure AD) para la autenticación basada en identidad de las solicitudes. Con Azure AD, puede usar el control de acceso basado en rol (RBAC) para conceder acceso a los recursos de Azure Event Grid a usuarios, grupos o aplicaciones.
Para enviar eventos a un tema o dominio con un TokenCredential, la identidad autenticada debe tener asignado el rol "Remitente de datos de EventGrid".
Con el paquete @azure/identity, puede autorizar sin problemas las solicitudes en entornos de desarrollo y producción. Para obtener más información sobre Azure Active Directory, consulte @azure/identity LÉAME.
Por ejemplo, puede usar DefaultAzureCredential para construir un cliente que se autenticará mediante Azure Active Directory:
const { EventGridPublisherClient } = require("@azure/eventgrid");
const { DefaultAzureCredential } = require("@azure/identity");
const client = new EventGridPublisherClient(
"<endpoint>",
"<endpoint schema>",
new DefaultAzureCredential(),
);
Conceptos clave
EventGridPublisherClient
EventGridPublisherClient se usa el envío de eventos a un tema de Event Grid o a un dominio de Event Grid.
Esquemas de eventos
Event Grid admite varios esquemas para codificar eventos. Cuando se crea un tema personalizado o un dominio, se especifica el esquema que se usará al publicar eventos. Aunque puede configurar el tema para que use un esquema personalizado es más común usar el esquema de Event Grid ya definido o esquema cloudEvents 1.0. CloudEvents es un proyecto de Cloud Native Computing Foundation que genera una especificación para describir los datos de eventos de una manera común. Al construir EventGridPublisherClient, debe especificar qué esquema está configurado para usar el tema:
Si el tema está configurado para usar el esquema de Event Grid, establezca "EventGrid" como tipo de esquema:
const client = new EventGridPublisherClient(
"<endpoint>",
"EventGrid",
new AzureKeyCredential("<API Key>"),
);
Si el tema está configurado para usar el esquema de eventos en la nube, establezca "CloudEvent" como tipo de esquema:
const client = new EventGridPublisherClient(
"<endpoint>",
"CloudEvent",
new AzureKeyCredential("<API Key>"),
);
Si el tema está configurado para usar un esquema de eventos personalizado, establezca "Personalizado" como tipo de esquema:
const client = new EventGridPublisherClient(
"<endpoint>",
"Custom",
new AzureKeyCredential("<API Key>"),
);
La construcción del cliente con un esquema diferente al que se configura el tema para esperar producirá un error del servicio y los eventos no se publicarán.
Puede ver qué esquema de entrada se ha configurado para un tema de Event Grid mediante el fragmento de código de la CLI de Azure
az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "inputSchema"
EventGridDeserializer
Los eventos entregados a los consumidores por Event Grid se entregan como JSON. Según el tipo de consumidor al que se entrega, el servicio Event Grid puede entregar uno o varios eventos como parte de una sola carga. Aunque estos eventos se pueden deserializar mediante métodos normales de JavaScript como JSON.parse, esta biblioteca ofrece un tipo auxiliar para deserializar eventos, denominados EventGridDeserializer.
En comparación con el uso de JSON.parse directamente, EventGridDeserializer realiza algunas conversiones adicionales durante los eventos de deserializng:
-
EventGridDeserializervalida que las propiedades necesarias de un evento están presentes y son los tipos correctos. -
EventGridDeserializerconvierte la propiedad event time en un objetoDatede JavaScript. - Al usar Eventos en la nube, los datos binarios se pueden usar para la propiedad de datos de un evento (mediante
Uint8Array). Cuando el evento se envía a través de Event Grid, se codifica en Base 64.EventGridDeserializerdescodificará estos datos en una instancia deUint8Array. - Al deserilar un de eventos del sistema de
(un evento generado por otro servicio de Azure), realizará conversiones adicionales para que el objeto coincida con la interfaz correspondiente que describe sus datos. Al usar TypeScript, estas interfaces garantizan que tiene una escritura segura al acceder a las propiedades del objeto de datos para un evento del sistema.
Al crear una instancia de EventGridDeserializer puede proporcionar deserializadores personalizados que se usan para convertir aún más el objeto data.
Seguimiento distribuido y eventos en la nube
Esta biblioteca admite el seguimiento distribuido mediante @azure/core-tracing. Al usar el seguimiento distribuido, esta biblioteca creará un intervalo durante una operación de send. Además, al enviar eventos mediante el esquema de Cloud Events 1.0, el SDK agregará metadatos de seguimiento distribuido a los eventos mediante la extensión de seguimiento distribuido . Los valores de las propiedades de extensión traceparent y tracestate corresponden a los encabezados traceparent y tracestate de la solicitud HTTP que envía los eventos. Si un evento ya tiene una propiedad de extensión traceparent no se actualiza.
Event Grid en Kubernetes
Esta biblioteca se ha probado y validado en Kubernetes mediante Azure Arc.
Ejemplos
Publicación de un evento personalizado en un tema de Event Grid mediante el esquema de 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",
},
},
]);
Publicación de un evento personalizado en un tema en un dominio de Event Grid mediante el esquema de Event Grid
La publicación de eventos en un dominio de Event Grid es similar a la publicación en un tema de Event Grid, excepto que cuando se usa el esquema de Event Grid para eventos, debe incluir la propiedad topic. Al publicar eventos en el esquema de Cloud Events 1.0, la propiedad source necesaria se usa como nombre del tema en el dominio para publicar en:
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",
},
},
]);
Deserializar un evento
EventGridDeserializer se puede usar para deserializar eventos entregados por Event Grid. En este ejemplo, tenemos un evento en la nube que se deserializa mediante EventGridDeserializer y usamos isSystemEvent para detectar qué tipo de eventos son.
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();
Solución de problemas
Registro
Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en el @azure/logger:
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.
Pasos siguientes
Eche un vistazo al directorio ejemplos para obtener ejemplos detallados sobre cómo usar esta biblioteca.
Contribuyendo
Si desea contribuir a esta biblioteca, lea la guía de contribución de para obtener más información sobre cómo compilar y probar el código.
Proyectos relacionados
Azure SDK for JavaScript