適用於 JavaScript 的 Azure 記憶體佇列用戶端連結庫 - 12.25.0 版

發行項
11/20/2024

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

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

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

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

主要連結：

開始

目前支持的環境

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

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

先決條件

安裝套件

安裝適用於 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 以取得您的入門。

相容性

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

Web 背景工作

此連結庫需要某些 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 記憶體佇列服務帳戶內的數據存放區，可在連線的客戶端之間傳送/接收訊息。

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

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

例子

匯入套件

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

const AzureStorageQueue = require("@azure/storage-queue");

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

const { QueueServiceClient, StorageSharedKeyCredential } = require("@azure/storage-queue");

建立佇列服務用戶端

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

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

具現化 QueueServiceClient 的建議方式

安裝程序：參考 - 授權從用戶端應用程式使用 Azure Active Directory 存取 Blob 和佇列 - /azure/storage/common/storage-auth-aad-app

註冊新的 AAD 應用程式，並授與代表登入使用者存取 Azure 記憶體的許可權
- 在 Azure Active Directory 中註冊新的應用程式（在 azure-portal 中） - /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 角色 - /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）。

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

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

使用連接字串

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

const { QueueServiceClient } = require("@azure/storage-queue");

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

搭配 `StorageSharedKeyCredential`

或者，您可以藉由傳遞 account-name 和 account-key 作為自變數，以 StorageSharedKeyCredential 具現化 QueueServiceClient。（帳戶名稱和帳戶密鑰可以從 Azure 入口網站取得。[僅適用於NODE.JS運行時間]

const { QueueServiceClient, StorageSharedKeyCredential } = require("@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
    telemetry: { value: "BasicSample/V11.0.0" } // Customized telemetry string
  }
);

使用SAS令牌

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

const { QueueServiceClient } = require("@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 語法：

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

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

main();

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

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

async function main() {
  const iter2 = queueServiceClient.listQueues();
  let i = 1;
  let item = await iter2.next();
  while (!item.done) {
    console.log(`Queue ${i++}: ${item.value.name}`);
    item = await iter2.next();
  }
}

main();

如需反覆運算佇列的完整範例，請參閱 samples/v12/typescript/listQueues.ts。

建立新的佇列

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

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const createQueueResponse = await queueClient.create();
  console.log(
    `Created queue ${queueName} successfully, service assigned request Id: ${createQueueResponse.requestId}`
  );
}

main();

將訊息傳送至佇列

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

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

const queueName = "<valid queue name>";

async function main() {
  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}`
  );
}

main();

查看訊息

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

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const peekMessagesResponse = await queueClient.peekMessages();
  console.log(`The peeked message is: ${peekMessagesResponse.peekedMessageItems[0].messageText}`);
}

main();

處理訊息

訊息會以兩個步驟處理。

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

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

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

const queueName = "<valid queue name>";

async function main() {
  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}`
    );
  }
}

main();

刪除佇列

const { DefaultAzureCredential } = require("@azure/identity");
const { QueueServiceClient } = require("@azure/storage-queue");

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

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

const queueName = "<valid queue name>";

async function main() {
  const queueClient = queueServiceClient.getQueueClient(queueName);
  const deleteQueueResponse = await queueClient.delete();
  console.log(
    `Deleted queue successfully, service assigned request Id: ${deleteQueueResponse.requestId}`
  );
}

main();

簡單 QueueServiceClient 案例的完整範例是 samples/v12/typescript/src/queueClient.ts。

故障排除

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

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

setLogLevel("info");

後續步驟

其他程式代碼範例

貢獻

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

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

共用方式為

適用於 JavaScript 的 Azure 記憶體佇列用戶端連結庫 - 12.25.0 版

開始

目前支持的環境

先決條件

安裝套件

驗證用戶端

Azure Active Directory

相容性

Web 背景工作

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

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

JavaScript 套件組合

CORS

重要概念

例子

匯入套件

建立佇列服務用戶端

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

使用連接字串

搭配 `StorageSharedKeyCredential`

使用SAS令牌

列出此帳戶中的佇列

建立新的佇列

將訊息傳送至佇列

查看訊息

處理訊息

刪除佇列

故障排除

後續步驟

貢獻

其他資源

共用方式為

適用於 JavaScript 的 Azure 記憶體佇列用戶端連結庫 - 12.25.0 版

開始

目前支持的環境

先決條件

安裝套件

驗證用戶端

Azure Active Directory

相容性

Web 背景工作

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

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

JavaScript 套件組合

CORS

重要概念

例子

匯入套件

建立佇列服務用戶端

從 @azure/identity 套件使用 DefaultAzureCredential

使用連接字串

搭配 StorageSharedKeyCredential

使用SAS令牌

列出此帳戶中的佇列

建立新的佇列

將訊息傳送至佇列

查看訊息

處理訊息

刪除佇列

故障排除

後續步驟

貢獻

其他資源

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

搭配 `StorageSharedKeyCredential`