Azure Event Grid-klientbibliotek för JavaScript – version 5.9.0

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

Använd klientbiblioteket för att:

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

Nyckellänkar:

• Källkod
• Package (NPM)
• API-referensdokumentation
• 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 supportprincip.

Förutsättningar

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

Om du använder Azure CLI ersätter du <your-resource-group-name> 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 komma åt Event Grid-API:et behöver du endpoint i event grid-ämnet och en 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 ditt Event Grid-ämne 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 Portal- 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 AzureKeyCredential för att autentisera 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 AzureSASCredential på följande sätt:

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

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.

Med @azure/identity-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 konstruera 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 för att använda ett anpassat schema är det vanligare att använda det redan definierade Event Grid-schema eller CloudEvents 1.0-schema. CloudEvents är ett Cloud Native Computing Foundation-projekt som genererar en specifikation för att beskriva händelsedata på ett vanligt sätt. När du skapar EventGridPublisherClient måste du ange vilket schema ditt ämne är konfigurerat 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 har konfigurerats för att använda Cloud Event Schema 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 att använda JSON.parse direkt gör EventGridDeserializer några ytterligare konverteringar medan 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 händelsetid till ett JavaScript-Date objekt.
3. När du använder Molnhändelser kan binära data användas för en händelses dataegenskap (med hjälp av Uint8Array). 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 avseriliserar en System Event (en händelse som genereras av en annan Azure-tjänst) gör EventGridDeserializer 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 typning när du får åtkomst till dataobjektets egenskaper 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 data objektet 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 intervall 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- och tracestate-tilläggsegenskaperna 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 hjälp av Event Grid-schemat

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

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

Deserialisera 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 hjälp av EventGridDeserializer och använder 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

Skogsavverkning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning 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 @azure/logger-paketdokumenten.

Nästa steg

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

Bidragande

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

Relaterade projekt

• Microsoft Azure SDK för Javascript