Azure Event Grid klientbibliotek för JavaScript – version 5.1.0-beta.1

Azure Event Grid är en molnbaserad tjänst som tillhandahåller tillförlitlig händelseleverans i massiv skala.

Använd klientbiblioteket för att:

• Skicka händelser till Event Grid med antingen Event Grid- eller Cloud Events 1.0-scheman eller ett anpassat schema
• Avkoda och bearbeta händelser som har levererats till en Event Grid-hanterare
• Generera signaturer för delad åtkomst för Event Grid-ämnen

Nyckellänkar:

• Källkod
• Paket (NPM)
• Referensdokumentation för API
• Produktdokumentation
• Exempel

Komma igång

Miljöer som stöds för närvarande

• LTS-versioner av Node.js
• De senaste versionerna av Safari, Chrome, Edge och Firefox.

Mer information finns i vår supportpolicy .

Förutsättningar

• En Azure-prenumeration.
• Ett befintligt Event Grid-ämne eller en befintlig domän. Om du behöver skapa resursen kan du använda Azure-portalen eller Azure CLI.

Om du använder Azure CLI ersätter <your-resource-group-name> du och <your-resource-name> med dina egna unika namn:

Skapa ett Event Grid-ämne

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

Skapa en Event Grid-domän

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

Installera @azure/eventgrid-paketet

Installera Azure Event Grid-klientbiblioteket för JavaScript med npm:

npm install @azure/eventgrid

Skapa och autentisera en EventGridPublisherClient

Om du vill skapa ett klientobjekt för att få åtkomst till Event Grid-API:et endpoint behöver du event grid-ämnet och .credential Event Grid-klienten kan använda antingen en åtkomstnyckel eller signatur för delad åtkomst (SAS) som skapats från en åtkomstnyckel.

Du hittar slutpunkten för event grid-ämnet antingen i Azure-portalen eller med hjälp av Azure CLI-kodfragmentet nedan:

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

Använda en åtkomstnyckel

Använd Azure-portalen för att bläddra till din Event Grid-resurs och hämta en åtkomstnyckel, eller använd Azure CLI-kodfragmentet nedan:

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

När du har en API-nyckel och slutpunkt kan du använda klassen för att autentisera AzureKeyCredential klienten på följande sätt:

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

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

Använda en SAS-token

Precis som en åtkomstnyckel ger en SAS-token åtkomst till att skicka händelser till ett Event Grid-ämne. Till skillnad från en åtkomstnyckel, som kan användas tills den återskapas, har en SAS-token en experationstid, då den inte längre är giltig. Om du vill använda en SAS-token för autentisering använder du följande AzureSASCredential :

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

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

Du kan generera en SAS-token med hjälp generateSharedAccessSigniture av funktionen .

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

Använda Azure Active Directory (AAD)

Azure EventGrid tillhandahåller integrering med Azure Active Directory (Azure AD) för identitetsbaserad autentisering av begäranden. Med Azure AD kan du använda rollbaserad åtkomstkontroll (RBAC) för att ge åtkomst till dina Azure Event Grid resurser till användare, grupper eller program.

Om du vill skicka händelser till ett ämne eller en domän med en TokenCredentialska den autentiserade identiteten ha rollen "EventGrid Data Sender" tilldelad.

@azure/identity Med paketet kan du smidigt auktorisera begäranden i både utvecklings- och produktionsmiljöer. Mer information om Azure Active Directory finns i @azure/identity README.

Du kan till exempel använda DefaultAzureCredential för att skapa en klient som ska autentisera med hjälp av Azure Active Directory:

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

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

Viktiga begrepp

EventGridPublisherClient

EventGridPublisherClient används för att skicka händelser till ett Event Grid-ämne eller en Event Grid-domän.

Händelsescheman

Event Grid stöder flera scheman för kodning av händelser. När ett anpassat ämne eller en domän skapas anger du det schema som ska användas vid publicering av händelser. Även om du kan konfigurera ämnet så att det använder ett anpassat schema är det vanligare att använda det redan definierade Event Grid-schemat eller CloudEvents 1.0-schemat. CloudEvents är ett Cloud Native Computing Foundation-projekt som skapar en specifikation för att beskriva händelsedata på ett vanligt sätt. När du skapar EventGridPublisherClient måste du ange vilket schema ämnet är konfigurerat för att använda:

Om ditt ämne har konfigurerats för att använda Event Grid-schemat anger du "EventGrid" som schematyp:

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

Om ditt ämne är konfigurerat för att använda molnhändelseschemat anger du "CloudEvent" som schematyp:

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

Om ditt ämne är konfigurerat för att använda ett anpassat händelseschema anger du "Anpassad" som schematyp:

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

Att konstruera klienten med ett annat schema än vad ämnet är konfigurerat att förvänta sig resulterar i ett fel från tjänsten och dina händelser publiceras inte.

Du kan se vilket indataschema som har konfigurerats för ett Event Grid-ämne med hjälp av Azure CLI-kodfragmentet nedan:

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

EventGridDeserializer

Händelser som levereras till konsumenter av Event Grid levereras som JSON. Beroende på vilken typ av konsument som levereras till kan Event Grid-tjänsten leverera en eller flera händelser som en del av en enda nyttolast. Även om dessa händelser kan deserialiseras med vanliga JavaScript-metoder som JSON.parse, erbjuder det här biblioteket en hjälptyp för deserialisering av händelser som kallas EventGridDeserializer.

Jämfört med direkt EventGridDeserializer användning JSON.parse utför vissa ytterligare konverteringar vid deserializng-händelser:

1. EventGridDeserializer verifierar att de nödvändiga egenskaperna för en händelse finns och är rätt typer.
2. EventGridDeserializer konverterar egenskapen för händelsetid till ett JavaScript-objekt Date .
3. När du använder Molnhändelser kan binära data användas för en händelses dataegenskap (med hjälp Uint8Arrayav ). När händelsen skickas via Event Grid kodas den i Bas 64. EventGridDeserializer avkodar dessa data till en instans av Uint8Array.
4. När du deseriliserar en systemhändelse (en händelse som genereras av en annan Azure-tjänst) EventGridDeserializer utför ytterligare konverteringar så att data objektet matchar motsvarande gränssnitt som beskriver dess data. När du använder TypeScript ser dessa gränssnitt till att du har stark inmatning när du kommer åt egenskaper för dataobjektet för en systemhändelse.

När du skapar en instans av EventGridDeserializer kan du ange anpassade deserialiserare som används för att konvertera objektet data ytterligare.

Distribuerade spårnings- och molnhändelser

Det här biblioteket stöder distribuerad spårning med hjälp av @azure/core-tracing. När du använder distribuerad spårning skapar det här biblioteket ett spann under en send åtgärd. När du skickar händelser med cloud events 1.0-schemat lägger SDK dessutom till distribuerade spårningsmetadata till händelserna med hjälp av tillägget distribuerad spårning. Värdena för traceparent egenskaperna och tracestate tillägg motsvarar traceparent - och tracestate -huvudena från HTTP-begäran som skickar händelserna. Om en händelse redan har en traceparent tilläggsegenskap uppdateras den inte.

Event Grid på Kubernetes

Det här biblioteket har testats och verifierats på Kubernetes med hjälp av Azure Arc.

Exempel

Publicera en anpassad händelse till ett Event Grid-ämne med hjälp av Event Grid-schemat

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

Publicera en anpassad händelse till ett ämne i en Event Grid-domän med event grid-schemat

Att publicera händelser till en Event Grid-domän liknar publicering till ett Event Grid-ämne, förutom att du måste inkludera topic egenskapen när du använder Event Grid-schemat för händelser. När du publicerar händelser i cloud events 1.0-schemat används den obligatoriska source egenskapen som namnet på ämnet i domänen som ska publiceras till:

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

Avserialisera en händelse

EventGridDeserializer kan användas för att deserialisera händelser som levereras av Event Grid. I det här exemplet har vi en molnhändelse som deserialiseras med och EventGridDeserializer används isSystemEvent för att identifiera vilken typ av händelser de är.

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

Felsökning

Loggning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg över HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Loggning kan också aktiveras vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggarna finns i dokumentationen om @azure-/loggningspaket.

Nästa steg

Ta en titt på exempelkatalogen för detaljerade exempel på hur du använder det här biblioteket.

Bidra

Om du vill bidra till det här biblioteket kan du läsa bidragsguiden om du vill veta mer om hur du skapar och testar koden.

Relaterade projekt

• Microsoft Azure SDK för Javascript