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
- LTS-versies van Node.js
- Nieuwste versies van Safari, Chrome, Edge en Firefox.
Zie ons ondersteuningsbeleid voor meer informatie.
Voorwaarden
- Een Azure-abonnement.
- Een bestaande Event Grid onderwerp of domein. Als u de resource wilt maken, kunt u de Azure Portal of Azure CLIgebruiken.
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 credential
nodig. 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, EventGridDeserializer
genoemd.
Vergeleken met het rechtstreeks gebruiken van JSON.parse
, voert EventGridDeserializer
extra conversies uit terwijl gebeurtenissen worden gedeserialiseerd:
-
EventGridDeserializer
valideert of de vereiste eigenschappen van een gebeurtenis aanwezig zijn en de juiste typen zijn. -
EventGridDeserializer
converteert de eigenschap gebeurtenistijd naar een JavaScript-Date
-object. - 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 vanUint8Array
. - Bij het deseriliseren van een System Event (een gebeurtenis die door een andere Azure-service wordt gegenereerd), voert
EventGridDeserializer
extra conversies uit, zodat hetdata
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.
Verwante projecten
Azure SDK for JavaScript