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

  • Artigo

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

Usar a biblioteca de clientes para enviar eventos para namespaces 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-namespaces

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

npm install @azure/eventgrid-namespaces

Criar e autenticar clientes de namespace

Para criar um objeto cliente para acessar a API de Namespaces da Grade de Eventos, você precisará do endpoint do tópico da Grade de Eventos e de um credential. Os clientes de Namespaces da Grade de Eventos podem usar 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 { EventGridSenderClient, EventGridReceiverClient, AzureKeyCredential } = require("@azure/eventgrid-namespaces");

const eventGridSenderClient = new EventGridSenderClient(
  "<endpoint>",
  new AzureKeyCredential("<Access Key>")
);

const eventGridReceiverClient = new EventGridReceiverClient(
  "<endpoint>",
  new AzureKeyCredential("<Access Key>")
);

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 @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 { EventGridSenderClient, EventGridReceiverClient } = require("@azure/eventgrid-namespaces");
const { DefaultAzureCredential } = require("@azure/identity");

const eventGridSenderClient = new EventGridSenderClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<topicName>"
);

const eventGridReceiverClient = new EventGridReceiverClient(
  "<endpoint>",
  new DefaultAzureCredential(),
  "<topicName>",
  "<subscriptionName>"
);

Principais conceitos

Enviando e recebendo eventos

EventGridSenderClient pode ser usado para enviar eventos para uma Grade de Eventos. Você pode inicializá-lo como:

const eventGridSenderClient = new EventGridSenderClient(
  "<endpoint>",
  new AzureKeyCredential("<API Key>"),
  "<topicName>"
);

EventGridReceiverClient pode ser usado para receber eventos de uma Grade de Eventos. Você pode inicializá-lo como:

const eventGridReceiverClient = new EventGridReceiverClient(
  "<endpoint>",
  new AzureKeyCredential("<API Key>"),
  "<topicName>",
  "<subscriptionName>"
);

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 send operação. Além disso, ao enviar eventos usando o esquema Cloud Events 1.0, o SDK adicionará metadados de rastreamento distribuído aos eventos usando a extensão de Rastreamento Distribuído. Os valores das propriedades de traceparent 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 em um tópico da Grade de Eventos

const { EventGridSenderClient, AzureKeyCredential } = require("@azure/eventgrid-namespaces");

const client = new EventGridSenderClient(
  "<endpoint>",
  new AzureKeyCredential("<API key>"),
  "<topicName>"
);

const cloudEvent: CloudEvent = {
  type: "example",
  source: "https://example.com",
  id: `singleEventIdV210001`,
  time: new Date(),
  data: {
    resourceUri: "https://dummyurl.com",
  },
  specversion: "1.0",
};
// Publish the Cloud Event
await client.sendEvents(cloudEvent);

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

Dê uma olhada no 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