JavaScript 用Azure Event Grid クライアントライブラリ - バージョン 5.4.0

[アーティクル]
04/10/2024

Azure Event Gridは、大規模な信頼性の高いイベント配信を提供するクラウドベースのサービスです。

以下の場合にクライアントライブラリを使用します。

Event Grid、Cloud Events 1.0 スキーマ、またはカスタムスキーマを使用して Event Grid にイベントを送信する
Event Grid ハンドラーに配信されたイベントをデコードして処理する
Event Grid トピックの Shared Access Signature を生成する

主要リンク:

はじめに

現在サポートされている環境

Node.js の LTS バージョン
Safari、Chrome、Edge、Firefox の最新バージョン。

詳細については、Microsoft のサポートポリシーを参照してください。

前提条件

Azure サブスクリプション。
既存の Event Grid トピックまたはドメイン。リソースを作成する必要がある場合は、 Azure Portal または Azure CLI を使用できます。

Azure CLI を使用する場合は、と <your-resource-name> を独自の一意の名前に置き換えます<your-resource-group-name>。

Event Grid トピックを作成する

az eventgrid topic create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

Event Grid ドメインを作成する

az eventgrid domain create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

`@azure/eventgrid` パッケージのインストール

を使用して JavaScript 用のAzure Event Grid クライアントライブラリをnpmインストールします。

npm install @azure/eventgrid

`EventGridPublisherClient` を作成して認証する

Event Grid API にアクセスするためのクライアントオブジェクトを作成するには、Event Grid トピックのと credentialが必要endpointです。 Event Grid クライアントでは、アクセスキーから作成されたアクセスキーまたは Shared Access Signature (SAS) を使用できます。

Event Grid トピックのエンドポイントは、 Azure Portal または以下の Azure CLI スニペットを使用して確認できます。

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

アクセスキーの使用

Azure Portal を使用して Event Grid リソースを参照し、アクセスキーを取得するか、次の Azure CLI スニペットを使用します。

az eventgrid topic key list --resource-group <your-resource-group-name> --name <your-event-grid-topic-name>

API キーとエンドポイントを取得したら、クラスを AzureKeyCredential 使用して、次のようにクライアントを認証できます。

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureKeyCredential("<Access Key>")
);

SAS トークンの使用

アクセスキーと同様に、SAS トークンを使用すると、Event Grid トピックへのイベントの送信にアクセスできます。再生成されるまで使用できるアクセスキーとは異なり、SAS トークンには使用時間があり、その時点で無効になります。認証に SAS トークンを使用するには、次のようにを AzureSASCredential 使用します。

const { EventGridPublisherClient, AzureSASCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureSASCredential("<SAS Token>")
);

関数を使用して SAS トークンを 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) の使用

Azure EventGrid は、要求の ID ベースの認証のために Azure Active Directory (Azure AD) と統合されます。 Azure AD では、ロールベースのアクセス制御 (RBAC) を使用して、Azure Event Grid リソースへのアクセス権をユーザー、グループ、またはアプリケーションに付与できます。

を使用 TokenCredentialしてトピックまたはドメインにイベントを送信するには、認証された ID に "EventGrid データ送信者" ロールが割り当てられている必要があります。

パッケージを @azure/identity 使用すると、開発環境と運用環境の両方で要求をシームレスに承認できます。 Azure Active Directory の詳細については、README に関するページを@azure/identity参照してください。

たとえば、を使用 DefaultAzureCredential して、Azure Active Directory を使用して認証するクライアントを構築できます。

const { EventGridPublisherClient } = require("@azure/eventgrid");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new DefaultAzureCredential()
);

主要な概念

EventGridPublisherClient

EventGridPublisherClient は、Event Grid トピックまたは Event Grid ドメインにイベントを送信するために使用されます。

イベントスキーマ

Event Grid では、イベントをエンコードするための複数のスキーマがサポートされています。カスタムトピックまたはドメインを作成するときは、イベントの発行時に使用するスキーマを指定します。 カスタムスキーマを使用するようにトピックを構成することもできますが、既に定義されている Event Grid スキーマまたは CloudEvents 1.0 スキーマを使用する方が一般的です。 CloudEvents は、一般的な方法でイベントデータを記述するための仕様を生成する Cloud Native Computing Foundation プロジェクトです。 EventGridPublisherClient を構築するときは、トピックで使用するように構成するスキーマを指定する必要があります。

Event Grid スキーマを使用するようにトピックが構成されている場合は、スキーマの種類として "EventGrid" を設定します。

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

Cloud イベントスキーマを使用するようにトピックが構成されている場合は、スキーマの種類として "CloudEvent" を設定します。

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

カスタムイベントスキーマを使用するようにトピックが構成されている場合は、スキーマの種類として "Custom" を設定します。

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

予期されるトピックとは異なるスキーマでクライアントを構築すると、サービスからエラーが発生し、イベントは発行されません。

次の Azure CLI スニペットを使用して、Event Grid トピックに対して構成されている入力スキーマを確認できます。

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "inputSchema"

EventGridDeserializer

Event Grid によってコンシューマーに配信されるイベントは、JSON として配信されます。配信されるコンシューマーの種類によっては、Event Grid サービスが 1 つのペイロードの一部として 1 つ以上のイベントを配信する場合があります。これらのイベントは、のような JSON.parse通常の JavaScript メソッドを使用して逆シリアル化できますが、このライブラリには、と呼ばれる EventGridDeserializerイベントを逆シリアル化するためのヘルパー型が用意されています。

を直接使用する場合と比較すると JSON.parse 、 EventGridDeserializer イベントの逆シリアル化中にいくつかの追加の変換が行われます。

EventGridDeserializer は、イベントの必須プロパティが存在し、適切な型であることを検証します。
EventGridDeserializer は、イベント時刻プロパティを JavaScript Date オブジェクトに変換します。
クラウドイベントを使用する場合、イベントのデータプロパティにバイナリデータを使用できます (を使用 Uint8Array)。イベントが Event Grid を介して送信されると、Base 64 でエンコードされます。 EventGridDeserializer は、このデータをの Uint8Arrayインスタンスにデコードし直します。
システムイベント (別の Azure サービスによって生成されたイベント) EventGridDeserializer をデサライズすると、オブジェクトがそのデータを記述する対応するインターフェイスと一致するようにdata、追加の変換が行われます。 TypeScript を使用する場合、これらのインターフェイスを使用すると、システムイベントのデータオブジェクトのプロパティにアクセスするときに、厳密な型指定が行われます。

の EventGridDeserializer インスタンスを作成するときに、オブジェクトをさらに変換するために使用されるカスタム逆シリアライザーを data 指定できます。

分散トレースとクラウドイベント

このライブラリでは、を使用した分散トレースが @azure/core-tracingサポートされています。分散トレースを使用する場合、このライブラリは操作中にスパンを send 作成します。さらに、Cloud Events 1.0 スキーマを使用してイベントを送信する場合、SDK は分散トレース拡張機能を使用して分散トレースメタデータをイベントに追加します。および tracestate 拡張プロパティのtraceparent値は、イベントをtraceparent送信する HTTP 要求のヘッダーと tracestate ヘッダーに対応します。イベントに既に traceparent 拡張プロパティがある場合、更新されません。

Kubernetes 上の Event Grid

このライブラリは、 Azure Arc を使用して Kubernetes でテストおよび検証されています。

例

Event Grid スキーマを使用して Event Grid トピックにカスタムイベントを発行する

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",
    },
  },
]);

Event Grid スキーマを使用して Event Grid ドメイン内のトピックにカスタムイベントを発行する

Event Grid ドメインへのイベントの発行は、Event Grid トピックへの発行と似ていますが、イベントに Event Grid スキーマを使用する場合は、プロパティを topic 含める必要があります。 Cloud Events 1.0 スキーマでイベントを発行する場合、発行先のドメイン内のトピックの名前として必須 source プロパティが使用されます。

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",
    },
  },
]);

イベントの逆シリアル化

EventGridDeserializer を使用して、Event Grid によって配信されるイベントを逆シリアル化できます。この例では、を使用して逆シリアル化され、を使用isSystemEventしてEventGridDeserializerイベントの種類を検出するクラウドイベントがあります。

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();

トラブルシューティング

ログ記録

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、環境変数 AZURE_LOG_LEVEL を info に設定します。または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

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

setLogLevel("info");

ログを有効にする方法の詳細については、 @azure/ロガーパッケージのドキュメントを参照してください。

次の手順

このライブラリの使用方法の詳細な例については、サンプルディレクトリを参照してください。

共同作成

このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

Microsoft Azure SDK for Javascript

インプレッション数

JavaScript 用Azure Event Grid クライアントライブラリ - バージョン 5.4.0

はじめに

現在サポートされている環境

前提条件

Event Grid トピックを作成する

Event Grid ドメインを作成する

`@azure/eventgrid` パッケージのインストール

`EventGridPublisherClient` を作成して認証する

アクセスキーの使用

SAS トークンの使用

Azure Active Directory (AAD) の使用

主要な概念

EventGridPublisherClient

イベントスキーマ

EventGridDeserializer

分散トレースとクラウドイベント

Kubernetes 上の Event Grid

例

Event Grid スキーマを使用して Event Grid トピックにカスタムイベントを発行する

Event Grid スキーマを使用して Event Grid ドメイン内のトピックにカスタムイベントを発行する

イベントの逆シリアル化

トラブルシューティング

ログ記録

次の手順

共同作成

フィードバック

その他のリソース

JavaScript 用Azure Event Grid クライアント ライブラリ - バージョン 5.4.0

はじめに

現在サポートされている環境

前提条件

Event Grid トピックを作成する

Event Grid ドメインを作成する

@azure/eventgrid パッケージのインストール

EventGridPublisherClient を作成して認証する

アクセス キーの使用

SAS トークンの使用

Azure Active Directory (AAD) の使用

主要な概念

EventGridPublisherClient

イベント スキーマ

EventGridDeserializer

分散トレースとクラウド イベント

Kubernetes 上の Event Grid

例

Event Grid スキーマを使用して Event Grid トピックにカスタム イベントを発行する

Event Grid スキーマを使用して Event Grid ドメイン内のトピックにカスタム イベントを発行する

イベントの逆シリアル化

トラブルシューティング

ログ記録

次の手順

共同作成

関連プロジェクト

フィードバック

その他のリソース

JavaScript 用Azure Event Grid クライアントライブラリ - バージョン 5.4.0

`@azure/eventgrid` パッケージのインストール

`EventGridPublisherClient` を作成して認証する

アクセスキーの使用

イベントスキーマ

分散トレースとクラウドイベント

Event Grid スキーマを使用して Event Grid トピックにカスタムイベントを発行する

Event Grid スキーマを使用して Event Grid ドメイン内のトピックにカスタムイベントを発行する