Azure Event Grid ügyfélkódtár JavaScripthez – 5.5.0-s verzió
Az Azure Event Grid egy felhőalapú szolgáltatás, amely nagy léptékben biztosít megbízható eseménykézbesítést.
Az ügyfélkódtár használatával:
- Események küldése az Event Gridbe az Event Grid, a Cloud Events 1.0 sémái vagy egy egyéni séma használatával
- Event Grid-kezelőnek kézbesített események dekódolása és feldolgozása
- Közös hozzáférésű jogosultságkódok létrehozása Event Grid-témakörökhöz
Főbb hivatkozások:
Első lépések
Jelenleg támogatott környezetek
- A Node.jsLTS-verziói
- A Safari, a Chrome, az Edge és a Firefox legújabb verziói.
További részletekért tekintse meg támogatási szabályzatunkat .
Előfeltételek
- Egy Azure-előfizetés.
- Egy meglévő Event Grid-témakör vagy tartomány. Ha létre kell hoznia az erőforrást, használhatja az Azure Portalt vagy az Azure CLI-t.
Ha az Azure CLI-t használja, cserélje le <your-resource-group-name>
a és <your-resource-name>
nevet a saját egyedi nevére:
Event Grid-témakör létrehozása
az eventgrid topic create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>
Event Grid-tartomány létrehozása
az eventgrid domain create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>
Telepítse a(z) @azure/eventgrid
csomagot
Telepítse a JavaScripthez készült Azure Event Grid-ügyfélkódtárat a következővel npm
:
npm install @azure/eventgrid
Hozzon létre és hitelesítsen egy EventGridPublisherClient
Ahhoz, hogy létrehozhasson egy ügyfélobjektumot az Event Grid API eléréséhez, szüksége lesz az endpoint
Event Grid-témakörre és egy credential
. Az Event Grid-ügyfél használhat hozzáférési kulcsból létrehozott hozzáférési kulcsot vagy közös hozzáférésű jogosultságkódot (SAS).
Az Event Grid-témakör végpontját az Azure Portalon vagy az alábbi Azure CLI-kódrészlettel találja meg:
az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"
Hozzáférési kulcs használata
Az Azure Portal használatával keresse meg az Event Grid-erőforrást, és kérjen le egy hozzáférési kulcsot, vagy használja az alábbi Azure CLI-kódrészletet :
az eventgrid topic key list --resource-group <your-resource-group-name> --name <your-event-grid-topic-name>
Miután rendelkezik API-kulccsal és végpontokkal, a AzureKeyCredential
osztály használatával hitelesítheti az ügyfelet az alábbiak szerint:
const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");
const client = new EventGridPublisherClient(
"<endpoint>",
"<endpoint schema>",
new AzureKeyCredential("<Access Key>")
);
SAS-jogkivonat használata
A hozzáférési kulcsokhoz hasonlóan az SAS-jogkivonatok is lehetővé teszik az események Event Grid-témakörbe való küldését. A hozzáférési kulccsal ellentétben, amely az újralétrehozásig használható, az SAS-jogkivonatnak experálási ideje van, amely időpontban már nem érvényes. HA SAS-jogkivonatot szeretne használni a hitelesítéshez, használja a AzureSASCredential
következőt:
const { EventGridPublisherClient, AzureSASCredential } = require("@azure/eventgrid");
const client = new EventGridPublisherClient(
"<endpoint>",
"<endpoint schema>",
new AzureSASCredential("<SAS Token>")
);
SAS-jogkivonatot a generateSharedAccessSigniture
függvény használatával hozhat létre.
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")
);
Az Azure Active Directory (AAD) használata
Az Azure EventGrid integrációt biztosít az Azure Active Directoryval (Azure AD) a kérések identitásalapú hitelesítéséhez. Az Azure AD-vel szerepköralapú hozzáférés-vezérléssel (RBAC) biztosíthat hozzáférést az Azure Event Grid-erőforrásokhoz felhasználók, csoportok vagy alkalmazások számára.
Ha eseményeket szeretne küldeni egy témakörbe vagy tartományba egy TokenCredential
használatával, a hitelesített identitáshoz hozzá kell rendelni az "EventGrid Data Sender" szerepkört.
A csomaggal zökkenőmentesen engedélyezheti a @azure/identity
kéréseket fejlesztési és éles környezetben is. További információ az Azure Active Directoryról: @azure/identity
README.
A használatával DefaultAzureCredential
például létrehozhat egy olyan ügyfelet, amely az Azure Active Directoryval fog hitelesíteni:
const { EventGridPublisherClient } = require("@azure/eventgrid");
const { DefaultAzureCredential } = require("@azure/identity");
const client = new EventGridPublisherClient(
"<endpoint>",
"<endpoint schema>",
new DefaultAzureCredential()
);
Fő fogalmak
EventGridPublisherClient
EventGridPublisherClient
Eseményt küld egy Event Grid-témakörnek vagy egy Event Grid-tartománynak.
Eseménysémák
Az Event Grid több sémát támogat az események kódolásához. Egyéni témakör vagy tartomány létrehozásakor meg kell adnia azt a sémát, amelyet az események közzétételekor használni fog. Bár a témakört egyéni séma használatára konfigurálhatja, gyakoribb a már definiált Event Grid-séma vagy a CloudEvents 1.0-séma használata. A CloudEvents egy Cloud Native Computing Foundation-projekt, amely egy specifikációt állít elő az eseményadatok közös leírásához. Az EventGridPublisherClient létrehozásakor meg kell adnia, hogy a témakör melyik sémát használja:
Ha a témakör az Event Grid-séma használatára van konfigurálva, állítsa be az "EventGrid" értéket sématípusként:
const client = new EventGridPublisherClient(
"<endpoint>",
"EventGrid",
new AzureKeyCredential("<API Key>")
);
Ha a témakör a felhőbeli eseményséma használatára van konfigurálva, állítsa a "CloudEvent" értéket sématípusként:
const client = new EventGridPublisherClient(
"<endpoint>",
"CloudEvent",
new AzureKeyCredential("<API Key>")
);
Ha a témakör egyéni eseményséma használatára van konfigurálva, állítsa az "Egyéni" értéket sématípusként:
const client = new EventGridPublisherClient(
"<endpoint>",
"Custom",
new AzureKeyCredential("<API Key>")
);
Ha az ügyfelet a témakör által várt sémától eltérő sémával hozza létre, az hibát fog eredményezni a szolgáltatásban, és az események nem lesznek közzétéve.
Az alábbi Azure CLI-kódrészlettel megtekintheti, hogy milyen bemeneti séma lett konfigurálva egy Event Grid-témakörhöz :
az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "inputSchema"
EventGridDeserializer
Az Event Grid által a fogyasztóknak küldött események JSON-ként lesznek kézbesítve. Attól függően, hogy milyen típusú fogyasztóhoz érkeznek, az Event Grid szolgáltatás egy vagy több eseményt is kézbesíthet egyetlen hasznos adat részeként. Bár ezek az események deszerializálhatók a szokásos JavaScript-metódusokkal( például JSON.parse
), ez a kódtár egy segédtípust biztosít az események deszerializálásához.EventGridDeserializer
A közvetlen használattal JSON.parse
összehasonlítva további konverziókat végez az EventGridDeserializer
események deszerializálása közben:
EventGridDeserializer
ellenőrzi, hogy egy esemény szükséges tulajdonságai jelen vannak-e, és hogy a megfelelő típusok-e.EventGridDeserializer
Az eseményidő tulajdonságot JavaScript-objektummáDate
alakítja.- Felhőesemények használatakor bináris adatok használhatók az esemény adattulajdonságához (a használatával
Uint8Array
). Amikor az eseményt az Event Griden keresztül küldi el, a 64-es alapkódban lesz kódolva.EventGridDeserializer
vissza fogja dekódolni ezeket az adatokat a példányábaUint8Array
. - Egy rendszeresemény (egy másik Azure-szolgáltatás által létrehozott esemény)
EventGridDeserializer
deszerilizálása további átalakításokat hajt végre, hogy azdata
objektum megfeleljen az adatokat leíró megfelelő felületnek. A TypeScript használatakor ezek az interfészek biztosítják, hogy erős gépelést használjon, amikor hozzáfér egy rendszeresemény adatobjektumának tulajdonságaihoz.
Egy példány EventGridDeserializer
létrehozásakor megadhat egyéni deszerializálókat, amelyek az data
objektum további átalakítására szolgálnak.
Elosztott nyomkövetési és felhőesemények
Ez a kódtár támogatja az elosztott nyomkövetést a használatával @azure/core-tracing
. Elosztott nyomkövetés használatakor ez a kódtár egy művelet során send
spant hoz létre. Emellett amikor a Cloud Events 1.0 sémával küld eseményeket, az SDK elosztott nyomkövetési metaadatokat ad hozzá az eseményekhez az Elosztott nyomkövetés bővítmény használatával. A és tracestate
a traceparent
bővítmény tulajdonságainak értékei az traceparent
eseményeket küldő HTTP-kérés és tracestate
fejléceinek felelnek meg. Ha egy esemény már rendelkezik traceparent
bővítménytulajdonságsal, az nem frissül.
Event Grid a Kubernetesen
Ezt a kódtárat teszteltük és ellenőriztük a Kubernetesben az Azure Arc használatával.
Példák
Egyéni esemény közzététele Event Grid-témakörben az Event Grid-sémával
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",
},
},
]);
Egyéni esemény közzététele egy Event Grid-tartomány témakörében az Event Grid-séma használatával
Az események Event Grid-tartományba való közzététele hasonló az Event Grid-témakörökben való közzétételhez, azzal a kivétellel, hogy az Event Grid-séma eseményekhez való használatakor a topic
tulajdonságot is tartalmaznia kell. Amikor eseményeket tesz közzé a Cloud Events 1.0 sémában, a rendszer a szükséges source
tulajdonságot használja a tartomány azon témakörének neveként, amellyel közzéteheti a következőket:
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",
},
},
]);
Esemény deszerializálása
EventGridDeserializer
az Event Grid által küldött események deszerializálására használható. Ebben a példában egy felhőesemény van, amely deszerializálva van a használatával EventGridDeserializer
, és a használatával isSystemEvent
észleli, hogy milyen típusú eseményekről van szó.
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();
Hibaelhárítás
Naplózás
A naplózás engedélyezése hasznos információkat deríthet fel a hibákról. A HTTP-kérések és -válaszok naplójának megtekintéséhez állítsa a környezeti változót értékre AZURE_LOG_LEVEL
info
. A naplózás futásidőben is engedélyezhető a következő hívásával setLogLevel
@azure/logger
:
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
A naplók engedélyezésének részletes útmutatásáért tekintse meg a @azure/logger csomag dokumentációját.
Következő lépések
A kódtár használatára vonatkozó részletes példákért tekintse meg a mintakönyvtárat.
Közreműködés
Ha hozzá szeretne járulni ehhez a kódtárhoz, olvassa el a közreműködői útmutatót , amelyből többet is megtudhat a kód buildeléséhez és teszteléséhez.
Kapcsolódó projektek
Azure SDK for JavaScript
Visszajelzés
https://aka.ms/ContentUserFeedback.
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ:Visszajelzés küldése és megtekintése a következőhöz: