Klientská knihovna Azure Event Gridu pro JavaScript – verze 5.5.1
Azure Event Grid je cloudová služba, která poskytuje spolehlivé doručování událostí ve velkém měřítku.
Klientskou knihovnu použijte k:
- Odesílání událostí do Event Gridu pomocí schémat Event Gridu, cloudových událostí 1.0 nebo vlastního schématu
- Dekódování a zpracování událostí, které byly doručeny obslužné rutině Event Gridu
- Generování sdílených přístupových podpisů pro témata event gridu
Klíčové odkazy:
Začínáme
Aktuálně podporovaná prostředí
- LTS verze Node.js
- Nejnovější verze Safari, Chrome, Edge a Firefox.
Další podrobnosti najdete v našich zásadách podpory .
Požadavky
- Předplatné Azure.
- Existující Event Grid tématu nebo doméně. Pokud potřebujete prostředek vytvořit, můžete použít webu Azure Portal nebo azure CLI.
Pokud používáte Azure CLI, nahraďte <your-resource-group-name>
a <your-resource-name>
vlastními jedinečnými názvy:
Vytvoření tématu Event Gridu
az eventgrid topic create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>
Vytvoření domény Event Gridu
az eventgrid domain create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>
Instalace balíčku @azure/eventgrid
Nainstalujte klientskou knihovnu Azure Event Grid pro JavaScript s npm
:
npm install @azure/eventgrid
Vytvoření a ověření EventGridPublisherClient
K vytvoření objektu klienta pro přístup k rozhraní API služby Event Grid budete potřebovat endpoint
tématu Event Gridu a credential
. Klient Event Gridu může použít přístupový klíč nebo sdílený přístupový podpis (SAS) vytvořený z přístupového klíče.
Koncový bod tématu služby Event Grid najdete na webu azure Portal nebo pomocí fragmentu kódu Azure CLI níže:
az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"
Použití přístupového klíče
Pomocí webu Azure Portal přejděte k prostředku služby Event Grid a načtěte přístupový klíč nebo použijte azure CLI fragment kódu níže:
az eventgrid topic key list --resource-group <your-resource-group-name> --name <your-event-grid-topic-name>
Jakmile máte klíč rozhraní API a koncový bod, můžete k ověření klienta použít třídu AzureKeyCredential
následujícím způsobem:
const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");
const client = new EventGridPublisherClient(
"<endpoint>",
"<endpoint schema>",
new AzureKeyCredential("<Access Key>")
);
Použití tokenu SAS
Podobně jako přístupový klíč token SAS umožňuje přístup k odesílání událostí do tématu Event Gridu. Na rozdíl od přístupového klíče, který lze použít, dokud se nevygeneruje, má token SAS dobu experace, v jakém okamžiku už není platný. Pokud chcete k ověřování použít token SAS, použijte AzureSASCredential
následujícím způsobem:
const { EventGridPublisherClient, AzureSASCredential } = require("@azure/eventgrid");
const client = new EventGridPublisherClient(
"<endpoint>",
"<endpoint schema>",
new AzureSASCredential("<SAS Token>")
);
Token SAS můžete vygenerovat pomocí funkce 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")
);
Použití Azure Active Directory (AAD)
Azure EventGrid poskytuje integraci se službou Azure Active Directory (Azure AD) pro ověřování požadavků na základě identit. Pomocí Azure AD můžete pomocí řízení přístupu na základě role (RBAC) udělit přístup k prostředkům Azure Event Gridu uživatelům, skupinám nebo aplikacím.
Pokud chcete odesílat události do tématu nebo domény s TokenCredential
, měla by mít ověřená identita přiřazenou roli EventGrid Data Sender.
S balíčkem @azure/identity
můžete bez problémů autorizovat požadavky v vývojových i produkčních prostředích. Další informace o Azure Active Directory najdete v
Můžete například použít DefaultAzureCredential
k vytvoření klienta, který se ověří pomocí Azure Active Directory:
const { EventGridPublisherClient } = require("@azure/eventgrid");
const { DefaultAzureCredential } = require("@azure/identity");
const client = new EventGridPublisherClient(
"<endpoint>",
"<endpoint schema>",
new DefaultAzureCredential()
);
Klíčové koncepty
EventGridPublisherClient
EventGridPublisherClient
se používá k odesílání událostí do tématu event Gridu nebo do domény Event Gridu.
Schémata událostí
Event Grid podporuje více schémat pro kódování událostí. Při vytvoření vlastního tématu nebo domény zadáte schéma, které se použije při publikování událostí. I když můžete své téma nakonfigurovat tak, aby používalo vlastní schéma je častější používat již definované schématu Event Gridu nebo schématu CloudEvents 1.0. CloudEvents je projekt Cloud Native Computing Foundation, který vytváří specifikaci pro popis dat událostí běžným způsobem. Při vytváření EventGridPublisherClient musíte určit, které schéma je vaše téma nakonfigurováno pro použití:
Pokud je vaše téma nakonfigurované tak, aby používalo schéma Event Gridu, nastavte "EventGrid" jako typ schématu:
const client = new EventGridPublisherClient(
"<endpoint>",
"EventGrid",
new AzureKeyCredential("<API Key>")
);
Pokud je vaše téma nakonfigurované tak, aby používalo schéma událostí cloudu, nastavte cloudEvent jako typ schématu:
const client = new EventGridPublisherClient(
"<endpoint>",
"CloudEvent",
new AzureKeyCredential("<API Key>")
);
Pokud je vaše téma nakonfigurované tak, aby používalo vlastní schéma událostí, nastavte jako typ schématu "Vlastní":
const client = new EventGridPublisherClient(
"<endpoint>",
"Custom",
new AzureKeyCredential("<API Key>")
);
Vytvoření klienta s jiným schématem, než jaké je téma nakonfigurované tak, aby očekávalo, způsobí chybu ze služby a vaše události nebudou publikovány.
Pomocí fragmentu kódu Azure CLI níže můžete zjistit, jaké vstupní schéma se pro téma Event Gridu nakonfigurovalo:
az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "inputSchema"
EventGridDeserializer
Události doručované příjemcům službou Event Grid se doručují jako JSON. Služba Event Grid může v závislosti na typu příjemce doručovat jednu nebo více událostí jako součást jedné datové části. I když tyto události mohou být deserializovány pomocí normálních javascriptových metod, jako je JSON.parse
, tato knihovna nabízí pomocný typ pro deserializaci událostí, které se nazývají EventGridDeserializer
.
Ve srovnání s použitím JSON.parse
přímo EventGridDeserializer
provede některé další převody při deserializaci událostí:
-
EventGridDeserializer
ověří, že jsou přítomny požadované vlastnosti události a že jsou správné typy. -
EventGridDeserializer
převede vlastnost času události na javascriptový objektDate
. - Při použití cloudových událostí lze binární data použít pro vlastnost dat události (pomocí
Uint8Array
). Když se událost odešle prostřednictvím Event Gridu, zakóduje se do base 64.EventGridDeserializer
tato data dekóduje zpět do instanceUint8Array
. - Při deserilování systémové události (událost vygenerovaná jinou službou Azure)
EventGridDeserializer
provede další převody tak, aby objektdata
odpovídal odpovídajícímu rozhraní, které popisuje jeho data. Při použití TypeScriptu tato rozhraní zajišťují silné psaní při přístupu k vlastnostem datového objektu pro systémovou událost.
Při vytváření instance EventGridDeserializer
můžete zadat vlastní deserializery, které se používají k dalšímu převodu data
objektu.
Distribuované trasování a cloudové události
Tato knihovna podporuje distribuované trasování pomocí @azure/core-tracing
. Při použití distribuovaného trasování vytvoří tato knihovna rozsah během operace send
. Kromě toho při odesílání událostí pomocí schématu Cloud Events 1.0 sada SDK přidá do událostí distribuovaná metadata trasování pomocí rozšíření Distribuované trasování. Hodnoty vlastností rozšíření traceparent
a tracestate
odpovídají hlavičce traceparent
a tracestate
z požadavku HTTP, který odesílá události. Pokud událost již má vlastnost rozšíření traceparent
, není aktualizována.
Event Grid v Kubernetes
Tato knihovna byla testována a ověřena na Kubernetes pomocí služby Azure Arc.
Příklady
Publikování vlastní události do tématu Event Gridu pomocí schématu Event Gridu
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",
},
},
]);
Publikování vlastní události do tématu v doméně Event Gridu pomocí schématu Event Gridu
Publikování událostí do domény Event Gridu se podobá publikování do tématu Event Gridu s tím rozdílem, že při použití schématu Event Gridu pro události musíte zahrnout vlastnost topic
. Při publikování událostí ve schématu Cloud Events 1.0 se požadovaná vlastnost source
použije jako název tématu v doméně k publikování do:
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",
},
},
]);
Deserializace události
EventGridDeserializer
lze použít k deserializaci událostí doručované službou Event Grid. V tomto příkladu máme cloudovou událost, která se deserializuje pomocí EventGridDeserializer
a používá isSystemEvent
k detekci typu událostí, které jsou.
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();
Řešení problémů
Protokolování
Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL
na info
. Případně můžete protokolování povolit za běhu voláním setLogLevel
v @azure/logger
:
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.
Další kroky
Podrobné příklady použití této knihovny najdete v ukázkách adresáři.
Přispívající
Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání a přečtěte si další informace o vytváření a testování kódu.
Související projekty
Azure SDK for JavaScript