Biblioteca de cliente da Grade de Eventos do Azure para JavaScript - versão 5.9.0
de Grade de Eventos do Azure é um serviço baseado em nuvem que fornece entrega confiável de eventos em grande escala.
Use a biblioteca de cliente para:
- Enviar eventos para a Grade de Eventos usando a Grade de Eventos, esquemas de Eventos na Nuvem 1.0 ou um esquema personalizado
- Decodificar e processar eventos que foram entregues a um manipulador de Grade de Eventos
- Gerar assinaturas de acesso compartilhado para tópicos da grade de eventos
Ligações principais:
Primeiros passos
Ambientes atualmente suportados
- Versões LTS do Node.js
- Versões mais recentes do Safari, Chrome, Edge e Firefox.
Consulte a nossa política de suporte para obter mais detalhes.
Pré-requisitos
- Uma subscrição do Azure.
- Uma Grade de Eventos existente Tópico ou Domínio. Se precisar criar o recurso, você pode usar o do 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 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 cliente 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á da endpoint do tópico da Grade de Eventos e de um credential. O cliente de Grade de Eventos pode usar uma Chave de Acesso ou uma Assinatura de Acesso Compartilhado (SAS) criada a partir de uma chave de acesso.
Você pode encontrar o ponto de extremidade para seu tópico de Grade de Eventos no do Portal do
az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"
Usando uma chave de acesso
Use o do Portal do
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ê pode 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 o 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 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 Azure Ative Directory (AAD)
O Azure EventGrid fornece integração com o Azure Ative Directory (Azure AD) 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 perfeitamente solicitações em ambientes de desenvolvimento e produção. Para saber mais sobre o Azure Ative Directory, consulte o @azure/identity LEIA-ME.
Por exemplo, use pode usar DefaultAzureCredential para construir um cliente que será autenticado usando o Azure Ative Directory:
const { EventGridPublisherClient } = require("@azure/eventgrid");
const { DefaultAzureCredential } = require("@azure/identity");
const client = new EventGridPublisherClient(
"<endpoint>",
"<endpoint schema>",
new DefaultAzureCredential()
);
Conceitos-chave
EventGridPublisherClient
EventGridPublisherClient é usado enviando eventos para um Tópico de Grade de Eventos ou um Domínio de Grade de Eventos.
Esquemas de eventos
A Grade de Eventos oferece suporte a vários esquemas para codificação de eventos. 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 de Grade de Eventos já definido ou esquema do CloudEvents 1.0. CloudEvents é um projeto da Cloud Native Computing Foundation que produz uma especificação para descrever dados de eventos de uma 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 Cloud Event Schema, 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 de Grade de Eventos usando o trecho de da CLI do
az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "inputSchema"
EventGridDeserializer
Os eventos entregues aos consumidores pela Event Grid são entregues como JSON. Dependendo do tipo de consumidor a ser entregue, o serviço de Grade de Eventos pode fornecer um ou mais eventos como parte de uma única carga útil. Embora esses eventos possam ser desserializados usando métodos JavaScript normais, como JSON.parse, esta 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 durante a desserialização de eventos:
-
EventGridDeserializervalida se as propriedades necessárias de um evento estão presentes e são os tipos corretos. -
EventGridDeserializerconverte a propriedade event time em um objeto JavaScriptDate. - Ao usar o Cloud Events, os dados binários podem ser usados para a propriedade de dados de um evento (usando
Uint8Array). Quando o evento é enviado através da Grade de Eventos, ele é codificado na Base 64.EventGridDeserializerdecodificará esses dados novamente em uma instância doUint8Array. - Ao deserilizar um de Eventos 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 digitação forte ao acessar as 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 na nuvem
Esta biblioteca suporta rastreamento distribuído usando @azure/core-tracing. Ao usar o rastreamento distribuído, essa biblioteca criará uma extensão durante uma operação de send. Além disso, ao enviar eventos usando o esquema do Cloud Events 1.0, o SDK adicionará metadados de rastreamento distribuído aos eventos usando a extensão Distributed Tracing. Os valores para as 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 no Kubernetes usando o Azure Arc.
Exemplos
Publicar um evento personalizado em um tópico de grade de eventos usando o esquema de 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 de grade de eventos usando o esquema de grade de eventos
A publicação de eventos em um Domínio de Grade de Eventos é semelhante à publicação em um Tópico de Grade de Eventos, exceto que, ao usar o esquema de Grade de Eventos para eventos, você deve incluir a propriedade topic. Ao publicar eventos no esquema do Cloud Events 1.0, a propriedade source necessária é usada como o nome do tópico no domínio para publicação 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",
},
},
]);
Desserializando um evento
EventGridDeserializer pode ser usado para desserializar eventos fornecidos pela Grade de Eventos. Neste exemplo, temos um evento de nuvem que é desserializado usando EventGridDeserializer e usar isSystemEvent para detetar que tipo de eventos 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
Registo
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 tempo de execução chamando setLogLevel no @azure/logger:
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
Para obter instruções mais detalhadas sobre como ativar os logs, você pode consultar os documentos do pacote @azure/logger.
Próximos passos
Por favor, dê uma olhada no exemplos diretório para obter exemplos detalhados sobre como usar esta biblioteca.
Contribuição
Se você quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.
Projetos relacionados
Azure SDK for JavaScript