Share via

Azure Event Grid JavaScript ügyfélkódtár – 5.4.0-s verzió

  • Cikk

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ése és feldolgozása
  • Közös hozzáférésű jogosultságkódok létrehozása Event Grid-témakörökhöz

Fő hivatkozások:

Első lépések

Jelenleg támogatott környezetek

További részletekért tekintse meg támogatási szabályzatunkat .

Előfeltételek

Ha az Azure CLI-t használja, cserélje le <your-resource-group-name> a és <your-resource-name> a 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ővelnpm:

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észlet használatával 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, az 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 kulcstól eltérően, amely az újragenerálásig használható, az SAS-jogkivonatnak van egy exponenciális ideje, 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. A Azure AD szerepköralapú hozzáférés-vezérléssel (RBAC) hozzáférést biztosíthat a Azure Event Grid erőforrásokhoz a felhasználók, csoportok vagy alkalmazások számára.

Ha egy témakörbe vagy tartományba szeretne eseményeket küldeni egy TokenCredentialadott témakörrel vagy tartománnyal, a hitelesített identitáshoz hozzá kell rendelni az "EventGrid Data Sender" szerepkört.

A @azure/identity csomaggal zökkenőmentesen engedélyezheti a kéréseket mind a fejlesztési, mind az éles környezetben. Az Azure Active Directoryval kapcsolatos további információkért tekintse meg a @azure/identity README című témakört.

A használatával DefaultAzureCredential például létrehozhat egy olyan ügyfelet, amely az Azure Active Directory használatával hitelesít:

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éma

Az Event Grid több sémát is 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 általános 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 az "EventGrid" értéket sématípusként:

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

Ha a témakör a Cloud Event Schema 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, a szolgáltatás hibát fog eredményezni, é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 jut el, 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 normál JavaScript-metódusokkal, például JSON.parse, ez a kódtár egy segédtípust kínál az események deszerializálásához, az úgynevezett EventGridDeserializer.

A közvetlen használattal JSON.parse összehasonlítva további átalakításokat végez az EventGridDeserializer események deszerializng közben:

  1. EventGridDeserializer ellenőrzi, hogy az esemény szükséges tulajdonságai jelen vannak-e, és hogy a megfelelő típusok-e.
  2. EventGridDeserializer Az eseményidő tulajdonságot JavaScript-objektummá Date alakítja.
  3. A Cloud Events 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 rendszer a 64-ben kódolja az eseményt. EventGridDeserializer vissza fogja kódolni ezeket az adatokat egy példányba Uint8Array.
  4. Egy rendszeresemény (egy másik Azure-szolgáltatás által létrehozott esemény) EventGridDeserializer deszerilizálásakor további átalakításokat hajt végre, hogy az data objektum megfeleljen az adatok leírását tartalmazó megfelelő felületnek. A TypeScript használatakor ezek az interfészek biztosítják, hogy erős gépelést biztosítson, 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álata esetén ez a kódtár egy művelet során létrehoz egy időtartamot send . Ezenkívül, 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érelem é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 az Azure Arc használatával teszteltük és ellenőriztük a Kubernetesben.

Példák

Egyéni esemény közzététele egy 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 ha az Event Grid-sémát használja az eseményekhez, a topic tulajdonságot is tartalmaznia kell. Amikor eseményeket tesz közzé a Cloud Events 1.0 sémában, a rendszer a tartomány témakörének neveként a szükséges source tulajdonságot használja a közzétételhez:

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 szállított események deszerializálására használható. Ebben a példában egy olyan felhőeseményt mutatunk be, amely deszerializálva van a használatával EventGridDeserializer és használatával isSystemEvent annak észlelésére, 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 segíthet a hibákról szóló hasznos információk feltárásában. A HTTP-kérések és válaszok naplójának megtekintéséhez állítsa a környezeti változót a AZURE_LOG_LEVEL értékre info. A naplózás futásidőben is engedélyezhető a következő hívással setLogLevel@azure/logger:

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

setLogLevel("info");

A naplók engedélyezésére vonatkozó részletesebb útmutatásért tekintse meg a @azure/logger csomag dokumentáció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 összeállításáról és teszteléséről.

Megjelenések