Azure Event Grid biblioteca cliente para JavaScript: versión 5.1.0-beta.1

  • Artículo

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 principales:

Introducción

Entornos admitidos actualmente

Para más información, consulte la directiva de compatibilidad.

Requisitos previos

Si usa la CLI de Azure, reemplace <your-resource-group-name> y <your-resource-name> por sus propios nombres únicos:

Crear un tema de Event Grid

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

Crear un dominio de Event Grid

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

Instalar el paquete @azure/eventgrid

Instale la biblioteca cliente de Azure Event Grid para JavaScript con npm:

npm install @azure/eventgrid

Crear y autenticar una EventGridPublisherClient

Para crear un objeto de cliente para acceder a la API de Event Grid, 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 Azure Portal o mediante el fragmento de código de la CLI de Azure siguiente:

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

Uso de una clave de acceso

Use Azure Portal para ir al recurso de Event Grid y recuperar una clave de acceso, o bien use el fragmento de código de la CLI de Azure siguiente:

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 AzureKeyCredential clase 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 lo AzureSASCredential siguiente:

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 generateSharedAccessSigniture función .

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 identidades 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 , TokenCredentialla identidad autenticada debe tener asignado el rol "Remitente de datos de EventGrid".

Con el @azure/identity paquete, puede autorizar sin problemas las solicitudes en entornos de desarrollo y producción. Para más información sobre Azure Active Directory, consulte el @azure/identity archivo 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 para enviar 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 dominio, se especifica el esquema que se usará al publicar eventos. Aunque puede configurar el tema para usar un esquema personalizado , es más común usar el esquema de Event Grid ya definido o el 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 el esquema que el tema está configurado para usar:

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 "Custom" 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 siguiente 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 entregue, 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 JSON.parse directo, EventGridDeserializer realiza algunas conversiones adicionales durante los eventos de deserializng:

  1. EventGridDeserializer valida que las propiedades necesarias de un evento están presentes y son los tipos correctos.
  2. EventGridDeserializer convierte la propiedad de hora del evento en un objeto JavaScript Date .
  3. Cuando se usan 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. EventGridDeserializer descodificará estos datos en una instancia de Uint8Array.
  4. Al anular un evento del sistema (un evento generado por otro servicio de Azure), EventGridDeserializer realizará conversiones adicionales para que el data objeto coincida con la interfaz correspondiente que describe sus datos. Al usar TypeScript, estas interfaces garantizan que tiene 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 data objeto.

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 send operación. Además, al enviar eventos mediante el esquema Cloud Events 1.0, el SDK agregará metadatos de seguimiento distribuidos a los eventos mediante la extensión De seguimiento distribuido. Los valores de las propiedades de extensión traceparent y tracestate corresponden a los traceparent encabezados y tracestate de la solicitud HTTP que envía los eventos. Si un evento ya tiene una traceparent propiedad de extensión, 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",
    },
  },
]);

Publicar 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 publicar en un tema de Event Grid, excepto que cuando se usa el esquema de Event Grid para eventos, debe incluir la topic propiedad . Al publicar eventos en el esquema cloud Events 1.0, la propiedad necesaria source 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",
    },
  },
]);

Deserialización de 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 usa 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

La habilitación del registro puede ayudar a descubrir información útil sobre los 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 @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 de ejemplos para obtener ejemplos detallados sobre cómo usar esta biblioteca.

Contribuciones

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.

Impresiones