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

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

クライアント ライブラリを使用して、次の手順を実行します。

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

主要なリンク:

• ソース コード の
• パッケージ (NPM)
• API リファレンス ドキュメントの
• 製品のドキュメント
• サンプル

はじめ

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

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

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

前提 条件

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

Azure CLI を使用する場合は、<your-resource-group-name> と <your-resource-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 パッケージをインストールする

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

npm install @azure/eventgrid

EventGridPublisherClient を作成して認証する

Event Grid API にアクセスするためのクライアント オブジェクトを作成するには、Event Grid トピックの endpoint と credentialが必要です。 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>")
);

generateSharedAccessSigniture 関数を使用して SAS トークンを生成できます。

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 Data Sender" ロールが割り当てられている必要があります。

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

たとえば、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>")
);

クラウド イベント スキーマを使用するようにトピックが構成されている場合は、スキーマの種類として "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 はイベントを逆シリアル化しながらいくつかの追加の変換を行います。

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

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

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

このライブラリは、@azure/core-tracingを使用した分散トレースをサポートしています。 分散トレースを使用する場合、このライブラリは、send 操作中にスパンを作成します。 さらに、クラウド イベント 1.0 スキーマを使用してイベントを送信する場合、SDK は、分散トレース拡張機能を使用して、分散トレース メタデータをイベントに追加します。 traceparent および tracestate 拡張プロパティの値は、イベントを送信する HTTP 要求の traceparent および 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 によって配信されるイベントを逆シリアル化できます。 この例では、EventGridDeserializer を使用して逆シリアル化され、isSystemEvent を使用してイベントの種類を検出するクラウド イベントがあります。

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/logger パッケージのドキュメントを参照してください。

次の手順

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

貢献

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

関連プロジェクト

• Microsoft Azure SDK for Javascript の