Partilhar via

Azure Event Grid biblioteca de cliente para JavaScript – versão 5.1.0-beta.1

  • Artigo

Azure Event Grid é um serviço baseado na cloud que fornece uma entrega de eventos fiável em grande escala.

Utilize a biblioteca de cliente para:

  • Enviar eventos para o Event Grid com o Event Grid, os esquemas de Eventos na Cloud 1.0 ou um esquema personalizado
  • Descodificar e processar eventos que foram entregues a um processador do Event Grid
  • Gerar Assinaturas de Acesso Partilhado para tópicos do Event Grid

Ligações principais:

Introdução

Ambientes atualmente suportados

Veja a nossa política de suporte para obter mais detalhes.

Pré-requisitos

Se utilizar a CLI do Azure, substitua <your-resource-group-name> e <your-resource-name> pelos seus próprios nomes exclusivos:

Criar um Tópico do Event Grid

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

Criar um Domínio do Event Grid

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 cliente do Azure Event Grid para JavaScript com npm:

npm install @azure/eventgrid

Criar e autenticar um EventGridPublisherClient

Para criar um objeto de cliente para aceder à API do Event Grid, precisará do endpoint tópico do Event Grid e de um credential. O cliente do Event Grid pode utilizar uma Chave de Acesso ou uma Assinatura de Acesso Partilhado (SAS) criada a partir de uma chave de acesso.

Pode encontrar o ponto final do tópico do Event Grid no portal do Azure ou com o fragmento da CLI do Azure abaixo:

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

Utilizar uma Chave de Acesso

Utilize o Portal do Azure para navegar para o recurso do Event Grid e obter uma Chave de Acesso ou utilize o fragmento da CLI do Azure abaixo:

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

Assim que tiver uma chave de API e um ponto final, pode utilizar a AzureKeyCredential classe para autenticar o cliente da seguinte forma:

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

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

Utilizar um Token de SAS

Tal como uma chave de acesso, um token de SAS permite o acesso ao envio de eventos para um tópico do Event Grid. Ao contrário de uma chave de acesso, que pode ser utilizada até ser regenerada, um token de SAS tem um tempo de transferência, altura em que já não é válido. Para utilizar um token de SAS para autenticação, utilize o AzureSASCredential seguinte:

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

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

Pode gerar um token de SAS com 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")
);

Utilizar o Azure Active Directory (AAD)

O Azure EventGrid fornece integração com o Azure Active Directory (Azure AD) para autenticação baseada em identidade de pedidos. Com Azure AD, pode utilizar o controlo de acesso baseado em funções (RBAC) para conceder acesso aos seus recursos Azure Event Grid a utilizadores, grupos ou aplicações.

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

Com o @azure/identity pacote, pode autorizar pedidos de forma totalmente integrada em ambientes de desenvolvimento e produção. Para saber mais sobre o Azure Active Directory, veja README@azure/identity.

Por exemplo, a utilização pode ser utilizada DefaultAzureCredential para construir um cliente que irá autenticar com o Azure Active Directory:

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

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

Conceitos-chave

EventGridPublisherClient

EventGridPublisherClient é utilizado para enviar eventos para um Tópico do Event Grid ou um Domínio do Event Grid.

Esquemas de Eventos

O Event Grid suporta vários esquemas para codificar eventos. Quando um Tópico Personalizado ou Domínio é criado, especifica o esquema que será utilizado ao publicar eventos. Embora possa configurar o tópico para utilizar um esquema personalizado , é mais comum utilizar o esquema do Event Grid já definido ou o esquema CloudEvents 1.0. O CloudEvents é um projeto do Cloud Native Computing Foundation que produz uma especificação para descrever dados de eventos de uma forma comum. Ao construir o EventGridPublisherClient, tem de especificar o esquema que o tópico está configurado para utilizar:

Se o tópico estiver configurado para utilizar o Esquema do Event Grid, defina "EventGrid" como o tipo de esquema:

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

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

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

Se o tópico estiver configurado para utilizar 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á num erro do serviço e os seus eventos não serão publicados.

Pode ver que esquema de entrada foi configurado para um tópico do Event Grid com o fragmento 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 pelo Event Grid são fornecidos como JSON. Dependendo do tipo de consumidor a que está a ser entregue, o serviço Event Grid pode fornecer um ou mais eventos como parte de um único payload. Embora estes eventos possam ser serializados com métodos JavaScript normais como JSON.parse, esta biblioteca oferece um tipo de programa auxiliar para anular a serialização de eventos, denominado EventGridDeserializer.

Em comparação com a utilização JSON.parse direta, EventGridDeserializer efetua algumas conversões adicionais enquanto deserializng 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 num objeto JavaScript Date .
  3. Ao utilizar Eventos na Cloud, os dados binários podem ser utilizados para a propriedade de dados de um evento (utilizando Uint8Array). Quando o evento é enviado através do Event Grid, é codificado na Base 64. EventGridDeserializer irá descodificar estes dados novamente numa instância de Uint8Array.
  4. Ao anular a deserção de um Evento do Sistema (um evento gerado por outro serviço do Azure), EventGridDeserializer serão efetuadas conversões adicionais para que o data objeto corresponda à interface correspondente que descreve os respetivos dados. Ao utilizar o TypeScript, estas interfaces garantem que tem uma escrita forte quando acede às propriedades do objeto de dados de um evento de sistema.

Ao criar uma instância do EventGridDeserializer , pode fornecer desserializadores personalizados que são utilizados para converter ainda mais o data objeto.

Rastreio Distribuído e Eventos na Cloud

Esta biblioteca suporta o rastreio distribuído com @azure/core-tracing. Ao utilizar o rastreio distribuído, esta biblioteca irá criar um intervalo durante uma send operação. Além disso, ao enviar eventos com o esquema Cloud Events 1.0, o SDK adicionará metadados de rastreio distribuídos aos eventos com a extensão Rastreio Distribuído. Os valores das propriedades e tracestate da traceparent extensão correspondem aos traceparent cabeçalhos e tracestate do pedido HTTP que envia os eventos. Se um evento já tiver uma traceparent propriedade de extensão, não será atualizado.

Event Grid no Kubernetes

Esta biblioteca foi testada e validada no Kubernetes com o Azure Arc.

Exemplos

Publicar um Evento Personalizado num Tópico do Event Grid com o Esquema do 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 um Evento Personalizado num Tópico num Domínio do Event Grid com o Esquema do Event Grid

A publicação de eventos num Domínio do Event Grid é semelhante à publicação de um Tópico do Event Grid, exceto que, ao utilizar o esquema do Event Grid para eventos, tem de incluir a topic propriedade . Ao publicar eventos no esquema Cloud Events 1.0, a propriedade necessária source é utilizada como o nome do tópico no domínio para publicar em:

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

Anular a serialização de um Evento

EventGridDeserializer pode ser utilizado para anular a serialização de eventos fornecidos pelo Event Grid. Neste exemplo, temos um evento na cloud que é desserializado através EventGridDeserializer da utilização e utilização isSystemEvent para detetar o tipo de eventos que 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();

Resolução de problemas

Registo

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos e respostas HTTP, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como ativar os registos, pode ver os documentos do pacote @azure/logger.

Passos seguintes

Veja o diretório de exemplos para obter exemplos detalhados sobre como utilizar esta biblioteca.

Contribuir

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

Impressões