Libreria client di Griglia di eventi di Azure per JavaScript - versione 5.5.1

griglia di eventi di Azure è un servizio basato sul cloud che offre una distribuzione affidabile di eventi su larga scala.

Usare la libreria client per:

• Inviare eventi a Griglia di eventi usando gli schemi Griglia di eventi, Eventi cloud 1.0 o uno schema personalizzato
• Decodificare ed elaborare gli eventi recapitati a un gestore di Griglia di eventi
• Generare firme di accesso condiviso per gli argomenti di Griglia di eventi

Collegamenti chiave:

• codice sorgente
• del pacchetto
• documentazione di riferimento dell'API
• documentazione del prodotto
• esempi di

Introduttiva

Ambienti attualmente supportati

• versioni LTS di Node.js
• Versioni più recenti di Safari, Chrome, Edge e Firefox.

Per altri dettagli, vedere i criteri di supporto .

Prerequisiti

• Una sottoscrizione di Azure .
• Oggetto griglia di eventi esistente argomento o dominio. Se è necessario creare la risorsa, è possibile usare il portale di Azure o l'interfaccia della riga di comando di Azure.

Se si usa l'interfaccia della riga di comando di Azure, sostituire <your-resource-group-name> e <your-resource-name> con i propri nomi univoci:

Creare un argomento di Griglia di eventi

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

Creare un dominio di Griglia di eventi

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

Installare il pacchetto @azure/eventgrid

Installare la libreria client di Griglia di eventi di Azure per JavaScript con npm:

npm install @azure/eventgrid

Creare ed autenticare un EventGridPublisherClient

Per creare un oggetto client per accedere all'API griglia di eventi, è necessario il endpoint dell'argomento di Griglia di eventi e un credential. Il client di Griglia di eventi può usare una chiave di accesso o una firma di accesso condiviso creata da una chiave di accesso.

È possibile trovare l'endpoint per l'argomento di Griglia di eventi nel del portale di Azure o usando il frammento di codice dell'interfaccia della riga di comando di Azure seguente:

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

Uso di una chiave di accesso

Usare il del portale di Azure per passare alla risorsa di Griglia di eventi e recuperare una chiave di accesso oppure usare il frammento di codice dell'interfaccia della riga di comando di Azure seguente:

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

Dopo aver creato una chiave API e un endpoint, è possibile usare la classe AzureKeyCredential per autenticare il client come indicato di seguito:

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

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

Uso di un token di firma di accesso condiviso

Come una chiave di accesso, un token di firma di accesso condiviso consente di accedere all'invio di eventi a un argomento di Griglia di eventi. A differenza di una chiave di accesso, che può essere usata fino a quando non viene rigenerata, un token di firma di accesso condiviso ha un tempo di experation, a quel punto non è più valido. Per usare un token di firma di accesso condiviso per l'autenticazione, usare il AzureSASCredential come indicato di seguito:

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

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

È possibile generare un token di firma di accesso condiviso usando la funzione 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")
);

Uso di Azure Active Directory (AAD)

Azure EventGrid offre l'integrazione con Azure Active Directory (Azure AD) per l'autenticazione basata su identità delle richieste. Con Azure AD è possibile usare il controllo degli accessi in base al ruolo per concedere l'accesso alle risorse di Griglia di eventi di Azure a utenti, gruppi o applicazioni.

Per inviare eventi a un argomento o a un dominio con un TokenCredential, all'identità autenticata deve essere assegnato il ruolo "Mittente dati EventGrid".

Con il pacchetto @azure/identity, è possibile autorizzare facilmente le richieste in ambienti di sviluppo e produzione. Per altre informazioni su Azure Active Directory, vedere @azure/identity README.

Ad esempio, è possibile usare DefaultAzureCredential per costruire un client che eseguirà l'autenticazione con Azure Active Directory:

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

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

Concetti chiave

EventGridPublisherClient

EventGridPublisherClient viene usato l'invio di eventi a un argomento di Griglia di eventi o a un dominio di Griglia di eventi.

Schemi eventi

Griglia di eventi supporta più schemi per la codifica degli eventi. Quando viene creato un argomento personalizzato o un dominio, specificare lo schema che verrà utilizzato durante la pubblicazione di eventi. Sebbene sia possibile configurare l'argomento per l'uso di uno schema personalizzato è più comune usare lo schema di Griglia di eventi già definito o schema CloudEvents 1.0. CloudEvents è un progetto Cloud Native Computing Foundation che produce una specifica per descrivere i dati degli eventi in modo comune. Quando si costruisce EventGridPublisherClient, è necessario specificare lo schema che l'argomento è configurato per l'uso:

Se l'argomento è configurato per l'uso dello schema di Griglia di eventi, impostare "EventGrid" come tipo di schema:

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

Se l'argomento è configurato per l'uso dello schema di eventi cloud, impostare "CloudEvent" come tipo di schema:

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

Se l'argomento è configurato per l'uso di uno schema eventi personalizzato, impostare "Custom" come tipo di schema:

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

La costruzione del client con uno schema diverso da quello che l'argomento è configurato per l'attesa genererà un errore dal servizio e gli eventi non verranno pubblicati.

È possibile visualizzare lo schema di input configurato per un argomento di Griglia di eventi usando il frammento di codice dell'interfaccia della riga di comando di Azure di seguito:

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

EventGridDeserializer

Gli eventi recapitati ai consumer da Griglia di eventi vengono recapitati come JSON. A seconda del tipo di consumer a cui viene recapitato, il servizio Griglia di eventi può recapitare uno o più eventi come parte di un singolo payload. Sebbene questi eventi possano essere deserializzati usando metodi JavaScript normali come JSON.parse, questa libreria offre un tipo helper per deserializzare gli eventi, denominati EventGridDeserializer.

Rispetto all'uso diretto di JSON.parse, EventGridDeserializer esegue alcune conversioni aggiuntive durante la deserializzazione degli eventi:

1. EventGridDeserializer convalida che le proprietà necessarie di un evento siano presenti e siano i tipi corretti.
2. EventGridDeserializer converte la proprietà dell'ora dell'evento in un oggetto Date JavaScript.
3. Quando si usano eventi cloud, i dati binari possono essere usati per la proprietà dei dati di un evento (usando Uint8Array). Quando l'evento viene inviato tramite Griglia di eventi, viene codificato in Base 64. EventGridDeserializer decodifica i dati in un'istanza di Uint8Array.
4. Quando si deserilizing a System Event (un evento generato da un altro servizio di Azure), EventGridDeserializer eseguirà conversioni aggiuntive in modo che l'oggetto data corrisponda all'interfaccia corrispondente che ne descrive i dati. Quando si usa TypeScript, queste interfacce garantiscono una digitazione avanzata quando si accede alle proprietà dell'oggetto dati per un evento di sistema.

Quando si crea un'istanza di EventGridDeserializer è possibile fornire deserializzatori personalizzati usati per convertire ulteriormente l'oggetto data.

Eventi cloud e traccia distribuita

Questa libreria supporta la traccia distribuita usando @azure/core-tracing. Quando si usa la traccia distribuita, questa libreria creerà un intervallo durante un'operazione di send. Inoltre, quando si inviano eventi usando lo schema Eventi cloud 1.0, l'SDK aggiungerà metadati di traccia distribuiti agli eventi usando l'estensione di traccia distribuita . I valori per le proprietà dell'estensione traceparent e tracestate corrispondono alle intestazioni traceparent e tracestate dalla richiesta HTTP che invia gli eventi. Se un evento ha già una proprietà di estensione traceparent non viene aggiornata.

Griglia di eventi in Kubernetes

Questa libreria è stata testata e convalidata in Kubernetes usando Azure Arc.

Esempi

Pubblicare un evento personalizzato in un argomento di Griglia di eventi usando lo schema di Griglia di eventi

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

Pubblicare un evento personalizzato in un argomento in un dominio di Griglia di eventi usando lo schema di Griglia di eventi

La pubblicazione di eventi in un dominio di Griglia di eventi è simile alla pubblicazione in un argomento di Griglia di eventi, ad eccezione del fatto che quando si usa lo schema di Griglia di eventi per gli eventi, è necessario includere la proprietà topic. Quando si pubblicano eventi nello schema Eventi cloud 1.0, la proprietà source richiesta viene usata come nome dell'argomento nel dominio in cui eseguire la pubblicazione:

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

Deserializzazione di un evento

EventGridDeserializer può essere usato per deserializzare gli eventi recapitati da Griglia di eventi. In questo esempio è presente un evento cloud deserializzato usando EventGridDeserializer e si usa isSystemEvent per rilevare il tipo di eventi.

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

Risoluzione dei problemi

Registrazione

L'abilitazione della registrazione può aiutare a individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel nel @azure/logger:

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto @azure/logger.

Passaggi successivi

Per esempi dettagliati su come usare questa libreria, vedere gli esempi di directory.

Contribuire

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

Progetti correlati

• Microsoft Azure SDK per Javascript