Griglia di eventi di Azure libreria client per JavaScript - versione 5.1.0-beta.1

Griglia di eventi di Azure è un servizio basato sul cloud che fornisce un recapito 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 eventi recapitati a un gestore di Griglia di eventi
• Generare firme di accesso condiviso per gli argomenti di Griglia di eventi

Collegamenti principali:

• Codice sorgente
• Pacchetto (NPM)
• Documentazione di riferimento delle API
• Documentazione del prodotto
• Esempi

Introduzione

Ambienti attualmente supportati

• Versioni LTS di Node.js
• Ultime versioni di Safari, Chrome, Edge e Firefox.

Per altre informazioni, vedere i criteri di supporto.

Prerequisiti

• Una sottoscrizione di Azure.
• Argomento o dominio di Griglia di eventi esistente. 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 Griglia di eventi di Azure per JavaScript con npm:

npm install @azure/eventgrid

Creare e autenticare un oggetto EventGridPublisherClient

Per creare un oggetto client per accedere all'API griglia di eventi, è necessario disporre dell'argomento endpoint di Griglia di eventi e di un oggetto 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 portale di Azure o usando il frammento di 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 portale di Azure per passare alla risorsa di Griglia di eventi e recuperare una chiave di accesso oppure usare il frammento di 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 ottenuto una chiave API e un endpoint, è possibile usare la AzureKeyCredential classe 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

Analogamente a 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 come AzureSASCredential segue:

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 generateSharedAccessSigniture funzione .

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 sull'identità delle richieste. Con Azure AD è possibile usare il controllo degli accessi in base al ruolo per concedere l'accesso alle risorse Griglia di eventi di Azure a utenti, gruppi o applicazioni.

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

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

Ad esempio, usare per DefaultAzureCredential costruire un client che esegua 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 per inviare 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 o un dominio personalizzato, specificare lo schema che verrà usato durante la pubblicazione di eventi. Anche se è possibile configurare l'argomento per l'uso di uno schema personalizzato , è più comune usare lo schema di Griglia di eventi già definito o lo 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 da usare per l'argomento:

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 aspettarsi 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 interfaccia della riga di comando di Azure seguente:

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. Anche se questi eventi possono essere deserializzati usando metodi JavaScript normali come JSON.parse, questa libreria offre un tipo helper per deserializzare gli eventi, denominati EventGridDeserializer.

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

1. EventGridDeserializer verifica 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 JavaScript Date .
3. Quando si usano eventi cloud, i dati binari possono essere usati per la proprietà dei dati di un evento (tramite Uint8Array). Quando l'evento viene inviato tramite Griglia di eventi, viene codificato in Base 64. EventGridDeserializer i dati verranno decodificati nuovamente in un'istanza di Uint8Array.
4. Quando si deserilizzare un evento di sistema (un evento generato da un altro servizio di Azure), EventGridDeserializer eseguirà conversioni aggiuntive in modo che l'oggetto corrisponda all'interfaccia data 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 specificare deserializzatori personalizzati utilizzati per convertire ulteriormente l'oggetto data .

Eventi di traccia distribuita e cloud

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

Griglia di eventi in Kubernetes

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

Esempio

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 topic proprietà . Quando si pubblicano eventi nello schema eventi cloud 1.0, la proprietà obbligatoria source viene usata come nome dell'argomento nel dominio in cui pubblicare:

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 è disponibile un evento cloud che viene deserializzato usando EventGridDeserializer e usato isSystemEvent per rilevare il tipo di eventi che sono.

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 consente di 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 in @azure/logger:

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

setLogLevel("info");

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

Passaggi successivi

Per esempi dettagliati su come usare questa libreria, vedere la directory degli esempi .

Contributo

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

Progetti correlati

• Microsoft Azure SDK per Javascript