Biblioteca de clientes da Grade de Eventos do Azure para JavaScript – versão 5.5.1

  • Artigo

da Grade de Eventos do Azure é um serviço baseado em nuvem que fornece entrega de eventos confiáveis em grande escala.

Use a biblioteca de clientes para:

  • Enviar eventos para a Grade de Eventos usando a Grade de Eventos, os esquemas de Eventos de Nuvem 1.0 ou um esquema personalizado
  • Decodificar e processar eventos que foram entregues a um manipulador da Grade de Eventos
  • Gerar assinaturas de acesso compartilhado para tópicos da Grade de Eventos

Links de chave:

Introdução

Ambientes com suporte no momento

Consulte nossa política de suporte para obter mais detalhes.

Pré-requisitos

  • Uma assinatura do Azure.
  • Um tópico ou domínio da Grade de Eventos existente. Se você precisar criar o recurso, poderá usar o portal do Azure ou da CLI do Azure.

Se você usar a CLI do Azure, substitua <your-resource-group-name> e <your-resource-name> por seus próprios nomes exclusivos:

Criar um tópico da grade de eventos

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

Criar um domínio da grade de eventos

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

Instalar o pacote @azure/eventgrid

Instale a biblioteca de clientes da Grade de Eventos do Azure para JavaScript com npm:

npm install @azure/eventgrid

Criar e autenticar um EventGridPublisherClient

Para criar um objeto cliente para acessar a API da Grade de Eventos, você precisará do endpoint do tópico da Grade de Eventos e de um credential. O cliente da Grade de Eventos pode usar uma Chave de Acesso ou SAS (Assinatura de Acesso Compartilhado) criada a partir de uma chave de acesso.

Você pode encontrar o ponto de extremidade do tópico da Grade de Eventos no portal do Azure ou usando o snippet de da CLI do Azure abaixo:

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

Usando uma chave de acesso

Use o portal do Azure para navegar até o recurso da Grade de Eventos e recuperar uma chave de acesso ou usar o snippet de da CLI do Azure abaixo:

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

Depois de ter uma chave de API e um ponto de extremidade, você poderá usar a classe AzureKeyCredential para autenticar o cliente da seguinte maneira:

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureKeyCredential("<Access Key>")
);

Usando um token SAS

Como uma chave de acesso, um token SAS permite acesso ao envio de eventos para um tópico da Grade de Eventos. Ao contrário de uma chave de acesso, que pode ser usada até ser regenerada, um token SAS tem um tempo de experação, momento em que ele não é mais válido. Para usar um token SAS para autenticação, use o AzureSASCredential da seguinte maneira:

const { EventGridPublisherClient, AzureSASCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureSASCredential("<SAS Token>")
);

Você pode gerar um token SAS usando a função 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")
);

Usando o AAD (Azure Active Directory)

O Azure EventGrid fornece integração com o Azure AD (Azure Active Directory) para autenticação baseada em identidade de solicitações. Com o Azure AD, você pode usar o RBAC (controle de acesso baseado em função) para conceder acesso aos recursos da Grade de Eventos do Azure a usuários, grupos ou aplicativos.

Para enviar eventos para um tópico ou domínio com um TokenCredential, a identidade autenticada deve ter a função "EventGrid Data Sender" atribuída.

Com o pacote @azure/identity, você pode autorizar diretamente solicitações em ambientes de desenvolvimento e produção. Para saber mais sobre o Azure Active Directory, consulte oLEIAME .

Por exemplo, o uso pode usar DefaultAzureCredential para construir um cliente que será autenticado usando o Azure Active Directory:

const { EventGridPublisherClient } = require("@azure/eventgrid");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new DefaultAzureCredential()
);

Principais conceitos

EventGridPublisherClient

EventGridPublisherClient é usado enviando eventos para um Tópico da Grade de Eventos ou um Domínio da Grade de Eventos.

Esquemas de eventos

A Grade de Eventos dá suporte a vários esquemas para eventos de codificação. Quando um tópico ou domínio personalizado é criado, especifique o esquema que será usado ao publicar eventos. Embora você possa configurar seu tópico para usar um esquema personalizado é mais comum usar o esquema da Grade de Eventos já definido ou de esquema do CloudEvents 1.0. CloudEvents é um projeto do Cloud Native Computing Foundation que produz uma especificação para descrever dados de eventos de maneira comum. Ao construir o EventGridPublisherClient, você deve especificar qual esquema seu tópico está configurado para usar:

Se o tópico estiver configurado para usar o Esquema de Grade de Eventos, defina "EventGrid" como o tipo de esquema:

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API Key>")
);

Se o tópico estiver configurado para usar o Esquema de Eventos na Nuvem, defina "CloudEvent" como o tipo de esquema:

const client = new EventGridPublisherClient(
  "<endpoint>",
  "CloudEvent",
  new AzureKeyCredential("<API Key>")
);

Se o tópico estiver configurado para usar um Esquema de Eventos Personalizado, defina "Personalizado" como o tipo de esquema:

const client = new EventGridPublisherClient(
  "<endpoint>",
  "Custom",
  new AzureKeyCredential("<API Key>")
);

Construir o cliente com um esquema diferente do que o tópico está configurado para esperar resultará em um erro do serviço e seus eventos não serão publicados.

Você pode ver qual esquema de entrada foi configurado para um tópico da Grade de Eventos usando a CLI do Azure snippet abaixo:

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

EventGridDeserializer

Os eventos entregues aos consumidores pela Grade de Eventos são entregues como JSON. Dependendo do tipo de consumidor que está sendo entregue, o serviço da Grade de Eventos pode fornecer um ou mais eventos como parte de um único conteúdo. Embora esses eventos possam ser desserializados usando métodos JavaScript normais como JSON.parse, essa biblioteca oferece um tipo auxiliar para desserializar eventos, chamado EventGridDeserializer.

Em comparação com o uso JSON.parse diretamente, EventGridDeserializer faz algumas conversões adicionais ao desserializar eventos:

  1. EventGridDeserializer valida que as propriedades necessárias de um evento estão presentes e são os tipos certos.
  2. EventGridDeserializer converte a propriedade de hora do evento em um objeto Date JavaScript.
  3. Ao usar eventos de nuvem, os dados binários podem ser usados para a propriedade de dados de um evento (usando Uint8Array). Quando o evento é enviado por meio da Grade de Eventos, ele é codificado na Base 64. EventGridDeserializer decodificará esses dados novamente em uma instância de Uint8Array.
  4. Ao desserializar um de Evento do Sistema (um evento gerado por outro serviço do Azure), fará conversões adicionais para que o objeto corresponda à interface correspondente que descreve seus dados. Ao usar o TypeScript, essas interfaces garantem que você tenha uma digitação forte ao acessar propriedades do objeto de dados para um evento do sistema.

Ao criar uma instância de EventGridDeserializer você pode fornecer desserializadores personalizados que são usados para converter ainda mais o objeto data.

Rastreamento distribuído e eventos de nuvem

Essa biblioteca dá suporte ao rastreamento distribuído usando @azure/core-tracing. Ao usar o rastreamento distribuído, essa biblioteca criará um intervalo durante uma operação de send. Além disso, ao enviar eventos usando o esquema de Eventos de Nuvem 1.0, o SDK adicionará metadados de rastreamento distribuídos aos eventos usando a extensão Rastreamento Distribuído. Os valores das propriedades de extensão traceparent e tracestate correspondem aos cabeçalhos traceparent e tracestate da solicitação HTTP que envia os eventos. Se um evento já tiver uma propriedade de extensão traceparent, ele não será atualizado.

Grade de Eventos no Kubernetes

Esta biblioteca foi testada e validada em Kubernetes usando o Azure Arc.

Exemplos

Publicar um evento personalizado em um tópico da Grade de Eventos usando o esquema da Grade de Eventos

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 um evento personalizado em um tópico em um domínio da grade de eventos usando o esquema de grade de eventos

A publicação de eventos em um Domínio da Grade de Eventos é semelhante à publicação em um Tópico da Grade de Eventos, exceto que, ao usar o esquema da Grade de Eventos para eventos, você deve incluir a propriedade topic. Ao publicar eventos no esquema eventos de nuvem 1.0, a propriedade source necessária é usada como o nome do tópico no domínio para publicar:

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",
    },
  },
]);

Desserializando um evento

EventGridDeserializer pode ser usado para desserializar eventos entregues pela Grade de Eventos. Neste exemplo, temos um evento de nuvem desserializado usando EventGridDeserializer e usamos isSystemEvent para detectar que tipo de eventos eles são.

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

Solucionando problemas

Log

Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar os logs, você pode examinar os documentos do pacote @azure/agente.

Próximas etapas

Examine os exemplos de diretório para obter exemplos detalhados sobre como usar essa biblioteca.

Contribuindo

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

impressões