Azure Event Grid clientbibliotheek voor JavaScript - versie 5.1.0-beta.1

Azure Event Grid is een cloudservice die betrouwbare gebeurtenislevering op grote schaal biedt.

Gebruik de clientbibliotheek voor het volgende:

• Gebeurtenissen verzenden naar Event Grid met behulp van de Event Grid-schema's, 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

Belangrijke koppelingen:

• Broncode
• Pakket (NPM)
• API-referentiedocumentatie
• Productdocumentatie
• Voorbeelden

Aan de slag

Momenteel ondersteunde omgevingen

• LTS-versies van Node.js
• Nieuwste versies van Safari, Chrome, Edge en Firefox.

Zie ons ondersteuningsbeleid voor meer informatie.

Vereisten

• Een Azure-abonnement.
• Een bestaand Event Grid-onderwerp of -domein. Als u de resource moet maken, kunt u azure portal of Azure CLI gebruiken.

Als u de Azure CLI gebruikt, vervangt u en <your-resource-name> door <your-resource-group-name> 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>

Installeer het pakket @azure/eventgrid

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

npm install @azure/eventgrid

Een maken en verifiëren EventGridPublisherClient

Als u een clientobject wilt maken voor toegang tot de Event Grid-API, hebt u de endpoint van uw Event Grid-onderwerp en een credentialnodig. De Event Grid-client kan gebruikmaken van een toegangssleutel of sas (Shared Access Signature) 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 onderstaande Azure CLI-fragment :

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 als volgt gebruiken om de client 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, waarna het niet meer geldig is. Als u een SAS-token wilt gebruiken voor verificatie, gebruikt u het AzureSASCredential volgende:

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

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 identiteit 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 leesmij@azure/identity voor meer informatie over Azure Active Directory.

Gebruik bijvoorbeeld om DefaultAzureCredential 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()
);

Belangrijkste concepten

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 het coderen van gebeurtenissen. 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-schema te gebruiken. CloudEvents is een Cloud Native Computing Foundation-project dat een specificatie produceert voor het beschrijven van gebeurtenisgegevens op een algemene manier. Wanneer u de EventGridPublisherClient maakt, moet u opgeven welk schema uw onderwerp moet gebruiken:

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 kunnen worden gedeserialiseerd met behulp van normale JavaScript-methoden zoals JSON.parse, biedt deze bibliotheek een helpertype voor het deserialiseren van gebeurtenissen, genaamd EventGridDeserializer.

Vergeleken met rechtstreeks gebruiken JSON.parse , EventGridDeserializer voert een aantal 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 gebeurtenistijdeigenschap naar een JavaScript-object Date .
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 hiermee worden deze gegevens weer gedecodeerd in een exemplaar van Uint8Array.
4. Bij het desiliseren van een systeem gebeurtenis (een gebeurtenis die wordt gegenereerd door een andere Azure-service), EventGridDeserializer worden extra conversies uitgevoerd, zodat het data object overeenkomt met de bijbehorende interface die de gegevens beschrijft. Wanneer u TypeScript gebruikt, zorgen deze interfaces ervoor dat u sterk kunt typen bij het openen van eigenschappen van het gegevensobject voor een systeem gebeurtenis.

Wanneer u een exemplaar van maakt, EventGridDeserializer kunt u aangepaste deserialisaties opgeven 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 bereik tijdens een send bewerking. Bij het verzenden van gebeurtenissen met behulp van het Cloud Events 1.0-schema voegt de SDK bovendien metagegevens voor gedistribueerde tracering toe aan de gebeurtenissen met behulp van de extensie Distributed Tracing. De waarden voor de traceparent extensie-eigenschappen en tracestate komen overeen met de traceparent headers en tracestate van de HTTP-aanvraag waarmee de gebeurtenissen worden verzonden. 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 wanneer u het Event Grid-schema voor gebeurtenissen gebruikt, u de topic eigenschap moet opnemen. Bij het publiceren van gebeurtenissen in het Cloud Events 1.0-schema 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 deserialiseren

EventGridDeserializer kan worden gebruikt om gebeurtenissen die door Event Grid worden geleverd, te deserialiseren. In dit voorbeeld hebben we een cloudgebeurtenis die wordt gedeserialiseerd met behulp van EventGridDeserializer en wordt gebruikt isSystemEvent om te detecteren welk type gebeurtenissen het 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();

Problemen oplossen

Logboekregistratie

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

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

setLogLevel("info");

Voor meer gedetailleerde instructies over het inschakelen van de logboeken kunt u de documentatie over het @azure-/loggerpakket bekijken.

Volgende stappen

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

Bijdragen

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

Verwante projecten

• Microsoft Azure SDK voor Javascript