共用方式為

適用於 JavaScript 的 Azure 服務總線用戶端連結庫 - 7.9.5 版

  • 發行項

Azure 服務總線 是 Microsoft 的高度可靠雲端傳訊服務。

在應用程式中使用用戶端連結庫@azure/service-bus

  • 將訊息傳送至 Azure 服務總線佇列或主題
  • 從 Azure 服務總線佇列或訂用帳戶接收訊息
  • 在 Azure 服務總線命名空間中建立/取得/刪除/更新/列出佇列/主題/訂用帳戶/規則。

@azure/service-bus第 7 版的資源：

重要連結：

注意：如果您使用 1.1.10 版或更新版本，而且想要移轉至此套件的最新版本，請參閱我們的 移轉指南，以從服務總線 V1 移至服務總線 V7

開始使用

安裝套件

使用 npm 安裝 Azure 服務總線用戶端連結庫的最新版本。

npm install @azure/service-bus

目前支援的環境

必要條件

設定 TypeScript

TypeScript 用戶必須安裝 Node 類型定義：

npm install @types/node

您也需要在tsconfig.json中開啟 compilerOptions.allowSyntheticDefaultImports 。 請注意，如果您已啟用 compilerOptions.esModuleInterop， allowSyntheticDefaultImports 預設會啟用 。 如需詳細資訊 ，請參閱 TypeScript 的編譯程式選項手冊 。

JavaScript 套件組合

若要在瀏覽器中使用此用戶端連結庫，您必須先使用套件組合器。 如需如何執行這項操作的詳細資訊，請參閱我們的 統合檔。

除了在此描述的內容之外，此連結庫還需要下列 NodeJS 核心內建模組的額外 polyfill，才能在瀏覽器中正常運作：

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

如需使用 polyfill 的詳細資訊，請參閱您最愛的套件組合工具檔。

React 原生支援

與瀏覽器類似，React Native 不支援此 SDK 連結庫所使用的一些 JavaScript API，因此您需要為它們提供 polyfill。 如需詳細資訊，請參閱 Messaging React Native 範例與 Expo 。

驗證用戶端

與服務總線的互動會從 ServiceBusClient 類別的實例開始。 您可以使用連接字串或使用 Azure Active Directory 認證向服務總線進行驗證。

使用連接字串

這個方法會將連接字串帶到您的服務總線實例。 您可以從 Azure 入口網站取得連接字串。

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

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

如需此建構函式的詳細資訊，請參閱 API 檔。

使用 Azure Active Directory 認證

使用 Azure Active Directory 進行驗證會使用 Azure 身分識別連結庫。

下列範例使用 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 作，請將服務總線的「範圍」設定為下列專案，以取得適當的令牌：

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

如需此建構函式的詳細資訊，請參閱 API 檔

重要概念

初始化 ServiceBusClient之後，您就可以與服務總線命名空間內的這些資源互動：

  • 佇列：允許傳送和接收訊息。 通常用於點對點通訊。
  • 主題：與佇列相反，主題更適合發佈/訂閱案例。 主題可以傳送至 ，但需要一個訂用帳戶，其中可以平行使用多個主題。
  • 訂用帳戶：從主題取用的機制。 每個訂用帳戶都是獨立的，並接收傳送至主題的每個訊息複本。 規則和篩選可用來量身打造特定訂用帳戶所接收的訊息。

如需這些資源的詳細資訊，請參閱 什麼是 Azure 服務總線？。

若要與這些資源互動，應該熟悉下列 SDK 概念：

請注意，應該先建立佇列、主題和訂用帳戶，再使用此連結庫。

範例

下列各節提供代碼段，這些代碼段涵蓋使用 Azure 服務總線的一些常見工作

傳送訊息

建立類別的 ServiceBusClient 實例之後，您可以使用 ServiceBusSendercreateSender 方法來 傳送 訊息。

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

有兩個 receiveMode可用。

  • “peekLock” - 在 peekLock 模式中，接收者在佇列上指定的持續時間內鎖定訊息。
  • “receiveAndDelete” - 在 receiveAndDelete 模式中，訊息會在收到時從服務總線中刪除。

如果未在選項中提供 receiveMode，則預設為 “peekLock” 模式。 您也可以在 「peekLock」 模式中 解決收到的訊息 。

您可以使用下列 3 種方式之一來使用此接收者來接收訊息：

取得訊息陣列

使用 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
}

解決訊息

收到訊息之後，您可以completeMessage()根據訊息的解決方式呼叫、 abandonMessage()deferMessage() 或 deadLetterMessage() 接收者。

若要深入瞭解，請閱讀 Settling Received Messages

無效信件佇列

寄不出的信件佇列是 子佇列。 每個佇列或訂用帳戶都有自己的寄不出的信件佇列。 寄不出的信件佇列會儲存透過) 明確寄不出的信件 (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"
});

您可以在這裡深入瞭解 會話的運作方式。

從會話接收訊息

使用會話需要您建立已啟用會話的佇列或訂用帳戶。 您可以在 這裏深入瞭解如何在入口網站中設定這項功能。

不同於啟用非會話的佇列或訂用帳戶，只有單一接收者可以隨時從會話讀取。 這是藉由 鎖定 服務總線處理的會話來強制執行。 就概念上，這類似於使用 peekLock 模式時訊息鎖定的運作方式 - 當訊息 (或會話) 鎖定您的接收者具有獨佔存取權時。

若要開啟和鎖定會話，請使用的 ServiceBusClient 實例來建立 SessionReceiver。

有兩種方式可選擇要開啟的會話：

  1. 指定 ， sessionId以鎖定具名會話。

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

  2. 請勿指定會話識別碼。在此情況下，服務總線會找到尚未鎖定的下一個可用會話。

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

    您可以透過 sessionId 上的 SessionReceiver屬性來尋找工作階段的名稱。 如果未在選項中提供 receiveMode，則會預設為 “peekLock” 模式。 您也可以解決以 「peekLock」 模式收到的 訊息 。

建立接收者之後，您可以使用 3 種方式來接收訊息：

您可以在這裡深入瞭解 會話的運作方式。

管理服務總線命名空間的資源

ServiceBusAdministrationClient 可讓您在 (佇列、主題和訂用帳戶的實體上，使用 CRUD 作業來管理命名空間，) 和訂用帳戶的規則。

  • 支援使用服務總線連接字串以及來自 @azure/identity 類似 之 ServiceBusClientAAD 認證的驗證。

注意：服務總線尚不支援設定命名空間的 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);

疑難排解

以下是開始診斷問題的一些初始步驟。 如需詳細資訊，請參閱 服務總線疑難解答指南。

AMQP 相依性

服務總線連結庫取決於 rhea-promise 連結庫來管理連線、透過 AMQP 通訊協定傳送和接收訊息。

記錄

使用此程式庫時，您可以設定下列環境變數來取得偵錯記錄。

  • 從服務總線 SDK 取得偵錯記錄
export DEBUG=azure*
  • 從服務總線 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

記錄至檔案

  1. DEBUG設定環境變數，如上所示
  2. 執行測試文稿，如下所示：
  • 從測試文稿的記錄語句會移至 out.log ，然後從 sdk 記錄語句移至 debug.log。 
    node your-test-script.js > out.log 2>debug.log
  • 從測試腳本和 sdk 記錄語句移至相同的檔案 out.log ，方法是將 stderr 重新導向至 stdout (&1) ，然後將 stdout 重新導向至檔案：
    node your-test-script.js >out.log 2>&1
  • 來自測試腳本和 sdk 的記錄語句會移至相同的檔案 out.log。 
      node your-test-script.js &> out.log

下一步

如需如何使用此連結庫來傳送和接收服務總線佇列、主題和訂用帳戶訊息的詳細範例，請參閱範例目錄。

參與

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。

曝光數