JavaScript 用Azure Service Bus クライアントライブラリ - バージョン 7.9.4

[アーティクル]
02/06/2024

Azure Service Busは、Microsoft の信頼性の高いクラウドメッセージングサービスです。

アプリケーションのクライアントライブラリ @azure/service-bus を使用して、

Azure Service Bus キューまたはトピックにメッセージを送信する
Azure Service Bus キューまたはサブスクリプションからメッセージを受信する
Azure Service Bus名前空間の作成/取得/削除/更新/リストキュー/トピック/サブスクリプション/ルール。

バージョン 7 の @azure/service-bus リソース:

主要リンク:

注: バージョン 1.1.10 以前を使用していて、このパッケージの最新バージョンに移行する場合は、Service Bus V1 から Service Bus V7 に移行するための移行ガイドを参照してください

作業の開始

パッケージをインストールする

npm を使用して、Azure Service Bus クライアントライブラリの最新バージョンをインストールします。

npm install @azure/service-bus

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

Node.js の LTS バージョン

前提条件

TypeScript の構成

TypeScript ユーザーには、ノードの種類の定義がインストールされている必要があります。

npm install @types/node

また、tsconfig.jsonでを有効にする compilerOptions.allowSyntheticDefaultImports 必要があります。を有効compilerOptions.esModuleInteropallowSyntheticDefaultImportsにした場合、既定ではが有効になっていることに注意してください。詳細については、「 TypeScript のコンパイラオプションハンドブック」を参照してください。

JavaScript バンドル

ブラウザーでこのクライアントライブラリを使用するには、まず bundler を使用する必要があります。これを行う方法の詳細については、バンドルに関するドキュメントを参照してください。

このライブラリでは、記述されている内容に加えて、次の NodeJS コア組み込みモジュール用の追加のポリフィルも必要です。これは、ブラウザーで正常に動作します。

buffer
os
path
process

Webpack を使用したバンドル

Webpack v5 を使用している場合は、次の開発依存関係をインストールできます

npm install --save-dev os-browserify path-browserify

次に、以下を webpack.config.js に追加します

 const path = require("path");
+const webpack = require("webpack");

 module.exports = {
   entry: "./src/index.ts",
@@ -12,8 +13,21 @@ module.exports = {
       },
     ],
   },
+  plugins: [
+    new webpack.ProvidePlugin({
+      process: "process/browser",
+    }),
+    new webpack.ProvidePlugin({
+      Buffer: ["buffer", "Buffer"],
+    }),
+  ],
   resolve: {
     extensions: [".ts", ".js"],
+    fallback: {
+      buffer: require.resolve("buffer/"),
+      os: require.resolve("os-browserify"),
+      path: require.resolve("path-browserify"),
+    },
   },

ロールアップを使用したバンドル

ロールアップバンドルを使用している場合は、次の開発依存関係をインストールします

npm install --save-dev @rollup/plugin-commonjs @rollup/plugin-inject @rollup/plugin-node-resolve

次に、次の内容を rollup.config.js に含めます。

+import nodeResolve from "@rollup/plugin-node-resolve";
+import cjs from "@rollup/plugin-commonjs";
+import shim from "rollup-plugin-shim";
+import inject from "@rollup/plugin-inject";

export default {
  // other configs
  plugins: [
+    shim({
+      fs: `export default {}`,
+      net: `export default {}`,
+      tls: `export default {}`,
+      path: `export default {}`,
+      dns: `export function resolve() { }`,
+    }),
+    nodeResolve({
+      mainFields: ["module", "browser"],
+      preferBuiltins: false,
+    }),
+    cjs(),
+    inject({
+      modules: {
+        Buffer: ["buffer", "Buffer"],
+        process: "process",
+      },
+      exclude: ["./**/package.json"],
+    }),
  ]
};

ポリフィルの使用の詳細については、お気に入りの bundler のドキュメントを参照してください。

React Native サポート

ブラウザーと同様に、React Nativeはこの SDK ライブラリで使用される一部の JavaScript API をサポートしていないため、ポリフィルを提供する必要があります。詳細については、「Messaging React Native sample with Expo」を参照してください。

クライアントを認証する

Service Bus との対話は、 ServiceBusClient クラスのインスタンスから始まります。 Service Bus に対する認証は、接続文字列または Azure Active Directory 資格情報を使用して行うことができます。

接続文字列の使用

このメソッドは、接続文字列を Service Bus インスタンスに取り込みます。この接続文字列は、Azure portal から取得できます。

const { ServiceBusClient } = require("@azure/service-bus");

const serviceBusClient = new ServiceBusClient("<connectionString>");

このコンストラクターの詳細については、 API ドキュメントを参照してください。

Azure Active Directory 資格情報の使用

Azure Active Directory での認証では、 Azure ID ライブラリが使用されます。

次の例では、ライブラリから使用できる多くの資格情報プロバイダーの 1 つである DefaultAzureCredential を @azure/identity 使用しています。

const { ServiceBusClient } = require("@azure/service-bus");
const { DefaultAzureCredential } = require("@azure/identity");

const fullyQualifiedNamespace = "<name-of-service-bus-namespace>.servicebus.windows.net";
const credential = new DefaultAzureCredential();
const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);

注: AAD に対してインターフェイスの独自の TokenCredential 実装を使用している場合は、service-bus の "スコープ" を次のように設定して、適切なトークンを取得します。

["https://servicebus.azure.net//user_impersonation"];

このコンストラクターの詳細については、API ドキュメントを参照してください。

主要な概念

を ServiceBusClient初期化したら、Service Bus 名前空間内で次のリソースを操作できます。

キュー: メッセージの送受信を許可します。多くの場合、ポイントツーポイント通信に使用されます。
トピック: キューとは対照的に、トピックは発行/サブスクライブのシナリオに適しています。トピックはに送信できますが、使用するサブスクリプションが必要です。このサブスクリプションには複数の並列が存在する可能性があります。
サブスクリプション: トピックから使用するメカニズム。各サブスクリプションは独立しており、トピックに送信された各メッセージのコピーを受信します。ルールとフィルターを使用して、特定のサブスクリプションで受信するメッセージを調整できます。

これらのリソースの詳細については、「Azure Service Busとは」を参照してください。

これらのリソースを操作するには、次の SDK の概念をよく理解している必要があります。

を使用して作成されたを使用して、キューまたはトピックにメッセージをServiceBusSenderServiceBusClient.createSender()送信します。
を使用して作成されたを使用して、キューまたはサブスクリプションからメッセージをServiceBusReceiverServiceBusClient.createReceiver()受信します。
または ServiceBusClient.acceptNextSession()を使用して作成されたを使用してServiceBusSessionReceiver、セッションが有効なキューまたはサブスクリプションからメッセージをServiceBusClient.acceptSession()受信します。

このライブラリを使用する前に、キュー、トピック、サブスクリプションを作成する必要があることに注意してください。

例

次のセクションでは、Azure Service Busを使用した一般的なタスクの一部をカバーするコードスニペットを示します

メッセージの送信
メッセージを受信する
メッセージを決済する
配信不能キュー
セッションを使用してメッセージを送信する
セッションからメッセージを受信する
Service Bus 名前空間のリソースを管理する
その他のサンプル

メッセージを送信する

クラスのインスタンスを作成したら、メッセージのServiceBusClient送信に使用できる createSender メソッドを使用してを取得ServiceBusSenderできます。

const sender = serviceBusClient.createSender("my-queue");

const messages = [
  { body: "Albert Einstein" },
  { body: "Werner Heisenberg" },
  { body: "Marie Curie" },
  { body: "Steven Hawking" },
  { body: "Isaac Newton" },
  { body: "Niels Bohr" },
  { body: "Michael Faraday" },
  { body: "Galileo Galilei" },
  { body: "Johannes Kepler" },
  { body: "Nikolaus Kopernikus" }
];

// sending a single message
await sender.sendMessages(messages[0]);

// sending multiple messages in a single call
// this will fail if the messages cannot fit in a batch
await sender.sendMessages(messages);

// Sends multiple messages using one or more ServiceBusMessageBatch objects as required
let batch = await sender.createMessageBatch();

for (let i = 0; i < messages.length; i++) {
  const message = messages[i];
  if (!batch.tryAddMessage(message)) {
    // Send the current batch as it is full and create a new one
    await sender.sendMessages(batch);
    batch = await sender.createMessageBatch();

    if (!batch.tryAddMessage(messages[i])) {
      throw new Error("Message too big to fit in a batch");
    }
  }
}
// Send the batch
await sender.sendMessages(batch);

メッセージを受信する

クラスのServiceBusClientインスタンスを作成したら、createReceiver メソッドを使用してを取得ServiceBusReceiverできます。

const receiver = serviceBusClient.createReceiver("my-queue");

利用できるのは 2 つあります receiveMode。

"peekLock" - peekLock モードでは、受信側はキューで指定された期間、メッセージをロックします。
"receiveAndDelete" - receiveAndDelete モードでは、メッセージは受信時に Service Bus から削除されます。

オプションに receiveMode が指定されていない場合、既定では "peekLock" モードになります。また、受信したメッセージを "peekLock" モードで解決することもできます。

この受信者は、次の 3 つの方法のいずれかでメッセージを受信できます。

メッセージの配列を取得する

メッセージの配列に解決される promise を返す receiveMessages 関数を使用します。

const myMessages = await receiver.receiveMessages(10);

subscribe メソッドを使用してメッセージハンドラーを設定し、必要な限り実行します。

完了したら、を呼び出 receiver.close() して、それ以上メッセージの受信を停止します。

const myMessageHandler = async (message) => {
  // your code here
  console.log(`message.body: ${message.body}`);
};
const myErrorHandler = async (args) => {
  console.log(
    `Error occurred with ${args.entityPath} within ${args.fullyQualifiedNamespace}: `,
    args.error
  );
};
receiver.subscribe({
  processMessage: myMessageHandler,
  processError: myErrorHandler
});

非同期反復子を使用する

getMessageIterator を使用してメッセージに対する非同期反復子を取得する

for await (let message of receiver.getMessageIterator()) {
  // your code here
}

メッセージを決済する

メッセージを受信したら、メッセージの決済方法に基づいて、受信側で、abandonMessage()、deferMessage()または deadLetterMessage() を呼び出completeMessage()すことができます。

詳細については、「受信メッセージのセトリング」を参照してください

配信不能キュー

配信不能キューは サブキューです。各キューまたはサブスクリプションには、独自の配信不能キューがあります。配信不能キューには、明示的に配信不能 (経由 receiver.deadLetterMessage()) されたメッセージ、または最大配信数を超えたメッセージが格納されます。

配信不能サブキューのレシーバーの作成は、サブスクリプションまたはキューのレシーバーの作成と似ています。

// To receive from a queue's dead letter sub-queue
const deadLetterReceiverForQueue = serviceBusClient.createReceiver("queue", {
  subQueueType: "deadLetter"
});

// To receive from a subscription's dead letter sub-queue
const deadLetterReceiverForSubscription = serviceBusClient.createReceiver("topic", "subscription", {
  subQueueType: "deadLetter"
});

// Dead letter receivers work like any other receiver connected to a queue
// ex:
const messages = await deadLetterReceiverForQueue.receiveMessages(5);

for (const message of messages) {
  console.log(`Dead lettered message: ${message.body}`);
}

配信不能キューをより徹底的に示す完全なサンプル:

セッションを使用してメッセージを送信する

セッションを使用するには、セッションが有効なキューまたはサブスクリプションを作成する必要があります。ポータルでこの機能を構成する方法の詳細については、こちらを参照してください。

セッションにメッセージを送信するには、を ServiceBusClient 使用して createSender を使用して送信者を作成します。

メッセージを送信するときは、メッセージのプロパティを sessionId 設定して、メッセージが適切なセッションに到達するようにします。

const sender = serviceBusClient.createSender("my-session-queue");
await sender.sendMessages({
  body: "my-message-body",
  sessionId: "my-session"
});

セッションのしくみの詳細については、こちらを参照してください。

セッションからメッセージを受信する

セッションを使用するには、セッションが有効なキューまたはサブスクリプションを作成する必要があります。ポータルでこの機能を構成する方法の詳細については、こちらを参照してください。

セッションが有効でないキューまたはサブスクリプションとは異なり、セッションから読み取ることができる受信者は 1 つだけです。これは、Service Bus によって処理されるセッション をロック することによって適用されます。概念的には、これはモードを使用 peekLock する場合のメッセージロックのしくみに似ています。メッセージ (またはセッション) がロックされている場合、受信者はそれに排他的にアクセスできます。

セッションを開いてロックするには、の ServiceBusClient インスタンスを使用して SessionReceiver を作成します。

開くセッションを選択するには、次の 2 つの方法があります。

名前付きセッションを sessionIdロックするを指定します。

const receiver = await serviceBusClient.acceptSession("my-session-queue", "my-session");

セッション ID は指定しないでください。この場合、Service Bus は、まだロックされていない次の使用可能なセッションを見つけます。
```
const receiver = await serviceBusClient.acceptNextSession("my-session-queue");
```
セッションの名前は、のプロパティSessionReceiverをsessionId使用して確認できます。オプションに receiveMode が指定されていない場合、既定では "peekLock" モードになります。また、受信したメッセージを "peekLock" モードで解決することもできます。

受信者が作成されたら、次の 3 つの方法からメッセージを受信できます。

メッセージの配列を取得する
メッセージハンドラーを使用してサブスクライブする
非同期反復子を使用する

セッションのしくみの詳細については、こちらを参照してください。

Service Bus 名前空間のリソースを管理する

ServiceBusAdministrationClient では、エンティティ (キュー、トピック、サブスクリプション) とサブスクリプションのルールに対する CRUD 操作を使用して名前空間を管理できます。

サービスバス接続文字列を使用した認証と、と同様のからの AAD 資格情報を使用した認証をServiceBusClientサポートします@azure/identity。

注: Service Bus では名前空間の CORS ルールの設定はまだサポートされていないため、 ServiceBusAdministrationClient Web セキュリティを無効にしないとブラウザーでは機能しません。詳細については、こちらを参照してください。

// Get the connection string from the portal
// OR
// use the token credential overload, provide the host name of your Service Bus instance and the AAD credentials from the @azure/identity library
const serviceBusAdministrationClient = new ServiceBusAdministrationClient("<connectionString>");

// Similarly, you can create topics and subscriptions as well.
const createQueueResponse = await serviceBusAdministrationClient.createQueue(queueName);
console.log("Created queue with name - ", createQueueResponse.name);

const queueRuntimeProperties = await serviceBusAdministrationClient.getQueueRuntimeProperties(
  queueName
);
console.log("Number of messages in the queue = ", queueRuntimeProperties.totalMessageCount);

await serviceBusAdministrationClient.deleteQueue(queueName);

参考用サンプル - administrationClient.ts

トラブルシューティング

問題の診断を開始するための最初の手順をいくつか次に示します。詳細については、 Service Bus トラブルシューティングガイドを参照してください。

AMQP 依存関係

Service Bus ライブラリは、AMQP プロトコルを介した接続の管理、メッセージの送受信を行う rhea-promise ライブラリに依存します。

ログ記録

このライブラリの使用時にデバッグログを表示するには、次の環境変数を取得します。

Service Bus SDK からのデバッグログの取得

export DEBUG=azure*

Service Bus SDK とプロトコルレベルライブラリからデバッグログを取得する。

export DEBUG=azure*,rhea*

メッセージ変換 (多くのコンソール/ディスク領域を消費する) を 表示しない 場合は、環境変数を DEBUG 次のように設定できます。

export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer

エラーのみに関心がある場合は、環境変数をDEBUG次のように設定できます。

export DEBUG=azure:service-bus:error,azure:core-amqp:error,rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow

ファイルへのログ記録

上記のように環境変数を設定するDEBUG
次のようにテストスクリプトを実行します。

テストスクリプトのログステートメントはに out.log 移動し、sdk のログステートメントはに移動します debug.log。
```
node your-test-script.js > out.log 2>debug.log
```
テストスクリプトと sdk からのログステートメントは、stderr を stdout (&1) にリダイレクトして同じファイル out.log に移動し、stdout をファイルにリダイレクトします。
```
node your-test-script.js >out.log 2>&1
```
テストスクリプトと sdk からのログステートメントは、同じファイル out.logに移動します。
```
  node your-test-script.js &> out.log
```

次の手順

このライブラリを使用して Service Bus キュー、トピック、サブスクリプションとの間でメッセージを送受信する方法の詳細な例については、サンプルディレクトリを参照してください。

共同作成

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

インプレッション数

次の方法で共有

JavaScript 用Azure Service Bus クライアントライブラリ - バージョン 7.9.4

作業の開始

パッケージをインストールする

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

前提条件

TypeScript の構成

JavaScript バンドル

Webpack を使用したバンドル

ロールアップを使用したバンドル

React Native サポート

クライアントを認証する

接続文字列の使用

Azure Active Directory 資格情報の使用

主要な概念

例

メッセージを送信する

メッセージを受信する

メッセージの配列を取得する

非同期反復子を使用する

メッセージを決済する

配信不能キュー

セッションを使用してメッセージを送信する

セッションからメッセージを受信する

Service Bus 名前空間のリソースを管理する

トラブルシューティング

AMQP 依存関係

ログ記録

ファイルへのログ記録

次の手順

共同作成

フィードバック

その他のリソース

次の方法で共有

JavaScript 用Azure Service Bus クライアント ライブラリ - バージョン 7.9.4

作業の開始

パッケージをインストールする

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

前提条件

TypeScript の構成

JavaScript バンドル

Webpack を使用したバンドル

ロールアップを使用したバンドル

React Native サポート

クライアントを認証する

接続文字列の使用

Azure Active Directory 資格情報の使用

主要な概念

例

メッセージを送信する

メッセージを受信する

メッセージの配列を取得する

メッセージ ハンドラーを使用してサブスクライブする

非同期反復子を使用する

メッセージを決済する

配信不能キュー

セッションを使用してメッセージを送信する

セッションからメッセージを受信する

Service Bus 名前空間のリソースを管理する

トラブルシューティング

AMQP 依存関係

ログ記録

ファイルへのログ記録

次の手順

共同作成

フィードバック

その他のリソース

JavaScript 用Azure Service Bus クライアントライブラリ - バージョン 7.9.4

メッセージハンドラーを使用してサブスクライブする