Delen via


Azure Event Grid-clientbibliotheek voor JavaScript - versie 5.9.0

Azure Event Grid- is een cloudservice die betrouwbare levering van gebeurtenissen op grote schaal biedt.

Gebruik de clientbibliotheek voor het volgende:

  • Gebeurtenissen verzenden naar Event Grid met behulp van de Event Grid-, Cloud Events 1.0-schema's of een aangepast schema
  • Gebeurtenissen decoderen en verwerken die zijn geleverd aan een Event Grid-handler
  • Shared Access Signatures genereren voor Event Grid-onderwerpen

Sleutelkoppelingen:

Slag

Momenteel ondersteunde omgevingen

Zie ons ondersteuningsbeleid voor meer informatie.

Voorwaarden

Als u de Azure CLI gebruikt, vervangt u <your-resource-group-name> en <your-resource-name> door uw eigen unieke namen:

Een Event Grid-onderwerp maken

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

Een Event Grid-domein maken

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

Het @azure/eventgrid-pakket installeren

Installeer de Azure Event Grid-clientbibliotheek voor JavaScript met npm:

npm install @azure/eventgrid

Een EventGridPublisherClient maken en verifiëren

Als u een clientobject wilt maken voor toegang tot de Event Grid-API, hebt u het endpoint van uw Event Grid-onderwerp en een credentialnodig. De Event Grid-client kan een toegangssleutel of Shared Access Signature (SAS) gebruiken die is gemaakt op basis van een toegangssleutel.

U vindt het eindpunt voor uw Event Grid-onderwerp in de Azure Portal of met behulp van het Azure CLI-fragment hieronder:

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

Een toegangssleutel gebruiken

Gebruik de Azure Portal om naar uw Event Grid-resource te bladeren en een toegangssleutel op te halen, of gebruik het Azure CLI codefragment hieronder:

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

Zodra u een API-sleutel en -eindpunt hebt, kunt u de AzureKeyCredential-klasse gebruiken om de client als volgt te verifiëren:

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

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

Een SAS-token gebruiken

Net als een toegangssleutel biedt een SAS-token toegang tot het verzenden van gebeurtenissen naar een Event Grid-onderwerp. In tegenstelling tot een toegangssleutel, die kan worden gebruikt totdat deze opnieuw wordt gegenereerd, heeft een SAS-token een experatietijd, op welk moment deze niet meer geldig is. Als u een SAS-token wilt gebruiken voor verificatie, gebruikt u de AzureSASCredential als volgt:

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

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

U kunt een SAS-token genereren met behulp van de functie 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")
);

Azure Active Directory (AAD) gebruiken

Azure EventGrid biedt integratie met Azure Active Directory (Azure AD) voor verificatie op basis van identiteiten van aanvragen. Met Azure AD kunt u op rollen gebaseerd toegangsbeheer (RBAC) gebruiken om toegang te verlenen tot uw Azure Event Grid-resources aan gebruikers, groepen of toepassingen.

Als u gebeurtenissen wilt verzenden naar een onderwerp of domein met een TokenCredential, moet aan de geverifieerde identiteit de rol EventGrid-gegevenszender zijn toegewezen.

Met het @azure/identity-pakket kunt u aanvragen naadloos autoriseren in zowel ontwikkel- als productieomgevingen. Zie de @azure/identity README-voor meer informatie over Azure Active Directory.

Gebruik bijvoorbeeld DefaultAzureCredential om een client te maken die wordt geverifieerd met behulp van Azure Active Directory:

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

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

Sleutelbegrippen

EventGridPublisherClient

EventGridPublisherClient wordt gebruikt voor het verzenden van gebeurtenissen naar een Event Grid-onderwerp of een Event Grid-domein.

Gebeurtenisschema's

Event Grid ondersteunt meerdere schema's voor coderingsgebeurtenissen. Wanneer een aangepast onderwerp of domein wordt gemaakt, geeft u het schema op dat wordt gebruikt bij het publiceren van gebeurtenissen. Hoewel u uw onderwerp kunt configureren voor het gebruik van een aangepast schema is het gebruikelijker om het al gedefinieerde Event Grid-schema of CloudEvents 1.0-schemate gebruiken. CloudEvents is een Cloud Native Computing Foundation-project dat een specificatie produceert voor het beschrijven van gebeurtenisgegevens op een gemeenschappelijke manier. Wanneer u de EventGridPublisherClient maakt, moet u opgeven welk schema uw onderwerp is geconfigureerd voor gebruik:

Als uw onderwerp is geconfigureerd voor het gebruik van het Event Grid-schema, stelt u EventGrid in als het schematype:

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

Als uw onderwerp is geconfigureerd voor het gebruik van het cloudgebeurtenisschema, stelt u CloudEvent in als het schematype:

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

Als uw onderwerp is geconfigureerd voor het gebruik van een aangepast gebeurtenisschema, stelt u 'Aangepast' in als het schematype:

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

Het samenstellen van de client met een ander schema dan wat het onderwerp is geconfigureerd om te verwachten, resulteert in een fout van de service en uw gebeurtenissen worden niet gepubliceerd.

U kunt zien welk invoerschema is geconfigureerd voor een Event Grid-onderwerp met behulp van het onderstaande Azure CLI-fragment:

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

EventGridDeserializer

Gebeurtenissen die door Event Grid aan consumenten worden geleverd, worden geleverd als JSON. Afhankelijk van het type consument dat wordt geleverd, kan de Event Grid-service een of meer gebeurtenissen leveren als onderdeel van één nettolading. Hoewel deze gebeurtenissen mogelijk worden gedeserialiseerd met behulp van normale JavaScript-methoden zoals JSON.parse, biedt deze bibliotheek een helpertype voor het deserialiseren van gebeurtenissen, EventGridDeserializergenoemd.

Vergeleken met het rechtstreeks gebruiken van JSON.parse, voert EventGridDeserializer extra conversies uit terwijl gebeurtenissen worden gedeserialiseerd:

  1. EventGridDeserializer valideert of de vereiste eigenschappen van een gebeurtenis aanwezig zijn en de juiste typen zijn.
  2. EventGridDeserializer converteert de eigenschap gebeurtenistijd naar een JavaScript-Date-object.
  3. Wanneer u cloud gebeurtenissen gebruikt, kunnen binaire gegevens worden gebruikt voor de gegevenseigenschap van een gebeurtenis (met behulp van Uint8Array). Wanneer de gebeurtenis wordt verzonden via Event Grid, wordt deze gecodeerd in Base 64. EventGridDeserializer worden deze gegevens weer gedecodeerd in een exemplaar van Uint8Array.
  4. Bij het deseriliseren van een System Event (een gebeurtenis die door een andere Azure-service wordt gegenereerd), voert EventGridDeserializer extra conversies uit, zodat het data object overeenkomt met de bijbehorende interface waarin de gegevens worden beschreven. Wanneer u TypeScript gebruikt, zorgen deze interfaces ervoor dat u sterk typt wanneer u toegangseigenschappen hebt van het gegevensobject voor een systeem gebeurtenis.

Wanneer u een exemplaar van EventGridDeserializer maakt, kunt u aangepaste deserializers leveren die worden gebruikt om het data-object verder te converteren.

Gedistribueerde tracering en cloudgebeurtenissen

Deze bibliotheek ondersteunt gedistribueerde tracering met behulp van @azure/core-tracing. Wanneer u gedistribueerde tracering gebruikt, maakt deze bibliotheek een periode tijdens een send bewerking. Bovendien voegt de SDK bij het verzenden van gebeurtenissen met behulp van het schema cloudgebeurtenissen 1.0 gedistribueerde traceringsmetagegevens toe aan de gebeurtenissen met behulp van de extensie gedistribueerde tracering. De waarden voor de eigenschappen van de traceparent en tracestate-extensie komen overeen met de traceparent en tracestate headers van de HTTP-aanvraag die de gebeurtenissen verzendt. Als een gebeurtenis al een traceparent extensie-eigenschap heeft, wordt deze niet bijgewerkt.

Event Grid in Kubernetes

Deze bibliotheek is getest en gevalideerd op Kubernetes met behulp van Azure Arc.

Voorbeelden

Een aangepaste gebeurtenis publiceren naar een Event Grid-onderwerp met behulp van het Event Grid-schema

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

Een aangepaste gebeurtenis publiceren naar een onderwerp in een Event Grid-domein met behulp van het Event Grid-schema

Het publiceren van gebeurtenissen naar een Event Grid-domein is vergelijkbaar met publiceren naar een Event Grid-onderwerp, behalve dat u bij het gebruik van het Event Grid-schema voor gebeurtenissen de eigenschap topic moet opnemen. Bij het publiceren van gebeurtenissen in het schema Cloud Events 1.0 wordt de vereiste source eigenschap gebruikt als de naam van het onderwerp in het domein om te publiceren naar:

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

Een gebeurtenis deserialisatie ongedaan maken

EventGridDeserializer kunnen worden gebruikt voor het deserialiseren van gebeurtenissen die door Event Grid worden geleverd. In dit voorbeeld hebben we een cloudgebeurtenis die wordt gedeserialiseerd met behulp van EventGridDeserializer en isSystemEvent gebruiken om te detecteren welk type gebeurtenissen ze zijn.

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

Probleemoplossing

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger:

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

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van de logboeken, kunt u de @azure/logger pakketdocumentenbekijken.

Volgende stappen

Bekijk de voorbeelden map voor gedetailleerde voorbeelden over het gebruik van deze bibliotheek.

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

indrukken