Grade de Eventos do Azure biblioteca de clientes para JavaScript – versão 5.1.0-beta.1

  • Artigo

Grade de Eventos do Azure é um serviço baseado em nuvem que fornece entrega de eventos confiável 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 principais:

Introdução

Ambientes com suporte no momento

Confira nossa política de suporte para mais detalhes.

Pré-requisitos

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 de 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 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 tópico da Grade de Eventos e de um credential. O cliente da Grade de Eventos pode usar uma Chave de Acesso ou UMA 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 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 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 AzureKeyCredential classe 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 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 generateSharedAccessSigniture função .

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 Active Directory (Azure AD) para autenticação baseada em identidade de solicitações. Com Azure AD, você pode usar o RBAC (controle de acesso baseado em função) para conceder acesso aos recursos Grade de Eventos do Azure aos 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 @azure/identity pacote, você pode autorizar diretamente solicitações em ambientes de desenvolvimento e produção. Para saber mais sobre o Azure Active Directory, consulte o @azure/identity LEIAME.

Por exemplo, use 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, você especifica 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 o esquema CloudEvents 1.0. CloudEvents é um projeto do Cloud Native Computing Foundation que produz uma especificação para descrever dados de evento 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 da 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 de 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 evento 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 o snippet da CLI do Azure 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 uma única carga. 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 direto, EventGridDeserializer faz algumas conversões adicionais durante eventos desserializng:

  1. EventGridDeserializer valida se as propriedades necessárias de um evento estão presentes e são os tipos certos.
  2. EventGridDeserializer converte a propriedade de tempo de evento em um objeto JavaScript Date .
  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 em Base 64. EventGridDeserializer decodificará esses dados novamente em uma instância do Uint8Array.
  4. Ao desserializar um evento do sistema (um evento gerado por outro serviço do Azure), EventGridDeserializer fará conversões adicionais para que o data objeto corresponda à interface correspondente que descreve seus dados. Ao usar o TypeScript, essas interfaces garantem que você tenha uma digitação forte ao acessar as propriedades do objeto de dados para um evento do sistema.

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

Eventos de rastreamento distribuído e 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 send operação. Além disso, ao enviar eventos usando o esquema Eventos de Nuvem 1.0, o SDK adicionará metadados de rastreamento distribuído aos eventos usando a extensão de Rastreamento Distribuído. Os valores das traceparent propriedades de extensão e tracestate correspondem aos traceparent cabeçalhos e tracestate da solicitação HTTP que envia os eventos. Se um evento já tiver uma traceparent propriedade de extensão, ele não será atualizado.

Grade de Eventos no Kubernetes

Essa biblioteca foi testada e validada no 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 da 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 topic propriedade . Ao publicar eventos no esquema Eventos de Nuvem 1.0, a propriedade necessária source é 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();

Solução de problemas

Registro em log

A habilitação do 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 log pode ser habilitado no runtime chamando setLogLevel em @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 de @azure/agente.

Próximas etapas

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

Contribuição

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

Impressões