適用於 JavaScript 的 Azure 儲存體佇列用戶端程式庫 - 12.28.1 版

Azure 記憶體佇列提供應用程式元件之間的雲端傳訊。在設計調整應用程式時，應用程式元件通常會分離，以便獨立調整。佇列記憶體會提供異步傳訊，以便在應用程式元件之間通訊，無論是在雲端、桌面、內部部署伺服器或行動裝置上執行。佇列記憶體也支援管理異步工作和建置程式工作流程。

此專案提供 JavaScript 中的用戶端連結庫，可讓您輕鬆地取用 Azure 記憶體佇列服務。

使用此套件中的用戶端連結庫來：

取得/設定佇列服務屬性
建立/列出/刪除佇列
傳送/接收/查看/清除/更新/刪除佇列訊息

主要連結：

入門指南

目前支持的環境

LTS 版本的 Node.js
最新版的 Safari、Chrome、Edge 和 Firefox。

如需詳細資訊，請參閱我們的支援原則。

Prerequisites

安裝套件

安裝適用於 JavaScript 的 Azure 記憶體佇列用戶端連結庫的慣用方式是使用 npm 套件管理員。在終端機視窗中輸入下列內容：

npm install @azure/storage-queue

驗證用戶端

Azure 記憶體支援數種方式進行驗證。若要與 Azure 佇列記憶體服務互動，您必須建立記憶體用戶端的實例，例如 QueueServiceClient 或 QueueClient。請參閱建立的範例，以深入了解驗證。

Azure Active Directory
共用金鑰
共用存取簽章

Azure Active Directory

Azure 佇列記憶體服務支援使用 Azure Active Directory 來驗證其 API 的要求。 @azure/identity 套件提供應用程式可用來執行這項作業的各種認證類型。如需詳細資訊和範例，請參閱自述檔以取得 @azure/identity 以取得您的入門。

Compatibility

此連結庫與 Node.js 和瀏覽器相容，並針對 LTS Node.js 版本（>=8.16.0）和最新版的 Chrome、Firefox 和 Edge 進行驗證。

Web Workers

此連結庫需要某些 DOM 對象在瀏覽器中使用時全域可用，Web 背景工作角色預設不會提供這些物件。您必須進行聚合填入，才能讓此連結庫在 Web 背景工作。

如需詳細資訊，請參閱我們的檔，以在 Web 背景工作角色中使用適用於 JS 的 Azure SDK

此連結庫取決於下列 DOM API，這些 API 需要在 Web 背景工作角色中使用時載入外部 polyfill：

Node.js 與瀏覽器之間的差異

Node.js 和瀏覽器運行時間之間有差異。開始使用此連結庫時，請注意標示為「僅適用於NODE.JS運行時間」API 或類別， 或 「只能在瀏覽器中使用」。

下列功能、介面、類別或函式僅適用於 Node.js

根據帳戶名稱和帳戶金鑰的共用金鑰授權
- StorageSharedKeyCredential
共用存取簽章（SAS）產生
- generateAccountSASQueryParameters()
- generateQueueSASQueryParameters()

JavaScript 套件組合

若要在瀏覽器中使用此用戶端連結庫，您必須先使用配套程式。有關如何執行此操作的詳細信息，請參閱我們的捆綁文件。

CORS

如果您需要為瀏覽器進行開發，您必須為記憶體帳戶設定跨原始資源分享（CORS）規則。移至 Azure 入口網站和 Azure 記憶體總管，尋找您的記憶體帳戶，為 Blob/佇列/檔案/資料表服務建立新的 CORS 規則。

例如，您可以建立下列 CORS 設定以進行偵錯。但請根據您的生產環境中的需求，仔細自定義設定。

允許的來源： *
允許的動詞：DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
允許的標頭： *
公開的標頭： *
年齡上限（秒）：86400

重要概念

佇列是 Azure 記憶體佇列服務帳戶內的數據存放區，可在連線的客戶端之間傳送/接收訊息。

我們連結庫中與這些服務相關的主要數據類型如下：

A QueueServiceClient 代表 Azure 儲存體佇列服務中指定 儲存體帳戶 的連線（透過 URL），並提供 API 來操作其佇列。它會向服務進行驗證，並可用來建立 QueueClient 物件，以及從服務建立、刪除、列出佇列。
A QueueClient 代表儲存體帳戶中的單一佇列。它可以用來操作佇列的訊息，例如在佇列中傳送、接收和查看訊息。

Examples

匯入套件

若要使用用戶端，請將套件匯入您的檔案：

import * as AzureStorageQueue from "@azure/storage-queue";

或者，選擇性地只匯入您需要的類型：

import { QueueServiceClient, StorageSharedKeyCredential } from "@azure/storage-queue";

建立佇列服務用戶端

QueueServiceClient 需要佇列服務和存取認證的 URL。它也會選擇性地接受 options 參數中的一些設定。

從 `DefaultAzureCredential` 套件使用 `@azure/identity`

具現化 QueueServiceClient 的建議方式

設定：參考 - 從用戶端應用程式使用 Azure Active Directory 授權訪問 blob 和佇列 - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

註冊新的 AAD 應用程式，並授與代表登入使用者存取 Azure 記憶體的許可權
- 在 Azure Active Directory 中註冊新應用程式（在 azure-portal 中） - https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
- 在 [API permissions] 區段中，選取 [Add a permission]，然後選擇 [Microsoft APIs]。
- 挑選 Azure Storage，然後選取 user_impersonation 旁的複選框，然後按兩下 [Add permissions]。這可讓應用程式代表登入的使用者存取 Azure 記憶體。
在 Azure 入口網站中使用 RBAC 授與 Azure 記憶體佇列數據的存取權
- blob 和佇列的 RBAC 角色 - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal.
- 在 Azure 入口網站中，移至您的記憶體帳戶，並將 儲存器佇列數據參與者 角色指派給 Access control (IAM) 索引標籤中已註冊的 AAD 應用程式（在 azure-portal 中記憶體帳戶的左側導覽列中）。
範例的環境設定
- 從 AAD 應用程式的概觀頁面，記下 CLIENT ID 和 TENANT ID。在 [憑證 & 秘密] 索引標籤中，建立秘密並記下。
- 請確定您有 AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET 作為環境變數，才能成功執行範例（可以利用 process.env）。

import { DefaultAzureCredential } from "@azure/identity";
import { QueueServiceClient } from "@azure/storage-queue";

const account = "<account>";
const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential,
);

[注意 - 上述步驟僅適用於 Node.js]

使用連接字串

或者，您可以使用具有完整連接字串做為自變數的 QueueServiceClient 靜態方法，具現化 fromConnectionString()。（您可以從 Azure 入口網站取得連接字串。[僅適用於NODE.JS運行時間]

import { QueueServiceClient } from "@azure/storage-queue";

const connectionString = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connectionString);

搭配 `StorageSharedKeyCredential`

或者，您可以通過傳遞和 as 參數來實例化 a QueueServiceClient 和 aStorageSharedKeyCredential。accountNameaccountKey （可以從 Azure 門戶獲取 account name 和 account key 的值。[僅在 NODE.JS 運行時可用]

import { StorageSharedKeyCredential, QueueServiceClient } from "@azure/storage-queue";

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  sharedKeyCredential,
  {
    retryOptions: { maxTries: 4 }, // Retry options
    userAgentOptions: {
      userAgentPrefix: "BasicSample V10.0.0",
    }, // Customized telemetry string
  },
);

使用SAS令牌

此外，您可以使用共用存取簽章來具現化 QueueServiceClient（SAS）。您可以從 Azure 入口網站取得 SAS 令牌，或使用 generateAccountSASQueryParameters()產生。

import { QueueServiceClient } from "@azure/storage-queue";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net?${sas}`,
);

列出此帳戶中的佇列

使用 QueueServiceClient.listQueues() 函式來反覆運算佇列，並搭配新的 for-await-of 語法：

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const item of queueServiceClient.listQueues()) {
  console.log(`Queue${i++}: ${item.name}`);
}

或者，如果沒有 for-await-of：

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const iterator = queueServiceClient.listQueues();
let { done, value } = await iterator.next();
while (!done) {
  console.log(`Queue${i++}: ${value.name}`);
  ({ done, value } = await iterator.next());
}

如需疊代佇列的完整範例，請參閱 samples/v12/typescript/listQueues.ts。

建立新的佇列

使用 QueueServiceClient.getQueueClient() 函式來建立新的佇列。

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const createQueueResponse = await queueClient.create();
console.log(
  `Created queue ${queueName} successfully, service assigned request Id: ${createQueueResponse.requestId}`,
);

將訊息傳送至佇列

使用 sendMessage() 將訊息新增至佇列：

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
// Send a message into the queue using the sendMessage method.
const sendMessageResponse = await queueClient.sendMessage("Hello World!");
console.log(
  `Sent message successfully, service assigned message Id: ${sendMessageResponse.messageId}, service assigned request Id: ${sendMessageResponse.requestId}`,
);

查看訊息

QueueClient.peekMessages() 允許在佇列前查看一或多個訊息。此呼叫不會防止其他程式代碼存取擷取的訊息。

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const peekMessagesResponse = await queueClient.peekMessages();
console.log(`The peeked message is: ${peekMessagesResponse.peekedMessageItems[0].messageText}`);

處理訊息

訊息會以兩個步驟處理。

第一次呼叫 queueClient.receiveMessages()。這讓從這個佇列讀取訊息的其他程式代碼看不到訊息，默認期間為 30 秒。
處理訊息時，請使用訊息的 queueClient.deleteMessage()呼叫 popReceipt。

如果您的程式代碼因硬體或軟體失敗而無法處理訊息，此雙步驟程式可確保程式代碼的另一個實例可以取得相同的訊息，然後再試一次。

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const response = await queueClient.receiveMessages();
if (response.receivedMessageItems.length === 1) {
  const receivedMessageItem = response.receivedMessageItems[0];
  console.log(`Processing & deleting message with content: ${receivedMessageItem.messageText}`);
  const deleteMessageResponse = await queueClient.deleteMessage(
    receivedMessageItem.messageId,
    receivedMessageItem.popReceipt,
  );
  console.log(
    `Delete message successfully, service assigned request Id: ${deleteMessageResponse.requestId}`,
  );
}

刪除佇列

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  new DefaultAzureCredential(),
);

const queueName = "<valid queue name>";
const queueClient = queueServiceClient.getQueueClient(queueName);
const deleteQueueResponse = await queueClient.delete();
console.log(
  `Deleted queue successfully, service assigned request Id: ${deleteQueueResponse.requestId}`,
);

簡單 QueueServiceClient 場景的完整示例位於 samples/v12/typescript/src/queueClient.ts。

Troubleshooting

啟用記錄可能有助於找出有關失敗的實用資訊。若要查看 HTTP 要求和回應的記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。或者，您可以在運行時間啟用記錄，方法是在 setLogLevel中呼叫 @azure/logger：

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

後續步驟

其他程式代碼範例

Contributing

如果您想要參與此連結庫，請閱讀參與指南，以深入瞭解如何建置和測試程序代碼。

另請參閱儲存體特定指南，以取得設定記憶體連結庫測試環境的其他資訊。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-17