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

發行項
06/13/2024

Azure 記憶體佇列提供應用程式元件之間的雲端傳訊。設計擴充性的應用程式時，會經常分離應用程式元件，以便進行個別擴充。佇列儲存體可針對應用程式元件間的通訊，提供非同步傳訊，無論應用程式元件是在雲端、桌面、內部部署伺服器或行動裝置上執行。佇列儲存體也支援管理非同步工作並建置處理工作流程。

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

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

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

重要連結：

開始使用

目前支援的環境

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

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

必要條件

安裝套件

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

npm install @azure/storage-queue

驗證用戶端

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

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/queue/file/table service 建立新的 CORS 規則， (s) 。

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

允許的來源： *
允許的動詞：DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
允許的標頭：*
公開的標頭：*
) 最長存留期 (秒：86400

重要概念

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

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

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

範例

匯入封裝

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

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

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

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

建立佇列服務用戶端

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

with `DefaultAzureCredential` from `@azure/identity` package

具現化的建議方式 QueueServiceClient

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

註冊新的 AAD 應用程式，並授與代表登入使用者存取 Azure 記憶體的許可權
- 在 azure-portal) - /azure/active-directory/develop/quickstart-register-app 中的 Azure Active Directory (中註冊新的應用程式
- 在區 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 入口網站中，移至您的記憶體帳戶，並從 azure 入口網站中記憶體帳戶左側導覽列中的索引卷標 (，將記憶體 佇列數據參與者 角色指派給已註冊的 AAD 應用程式 Access control (IAM)) 。
範例的環境設定
- 從 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]

使用連接字串

或者，您可以使用靜態方法，搭配完整的連接字串做為自變數來具現化 QueueServiceClientfromConnectionString() 。 (可從 azure 入口網站取得連接字串。) [僅適用於 NODE.JS RUNTIME]

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

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

with `StorageSharedKeyCredential`

或者，您可以藉由傳遞 account-name 和 account-key 作為自變數，來具現化 QueueServiceClientStorageSharedKeyCredential 。 (可以從 azure 入口網站取得帳戶名稱和帳戶密鑰。) [僅適用於 NODE.JS RUNTIME]

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()SAS 令牌。

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() {
  let 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() {
  let 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。或者，您可以在 @azure/logger 中呼叫 setLogLevel，以在執行階段啟用記錄：

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

setLogLevel("info");

後續步驟

更多程式碼範例

參與

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

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

曝光數

共用方式為

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

開始使用

目前支援的環境

必要條件

安裝套件

驗證用戶端

Azure Active Directory

相容性

Web 背景工作

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

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

JavaScript 套件組合

CORS

重要概念

範例

匯入封裝

建立佇列服務用戶端

with `DefaultAzureCredential` from `@azure/identity` package

使用連接字串

with `StorageSharedKeyCredential`

使用SAS令牌

列出此帳戶中的佇列

建立新佇列

將訊息傳送至佇列

瞄核訊息

處理訊息

刪除佇列

疑難排解

後續步驟

參與

意見反應

其他資源

共用方式為

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

開始使用

目前支援的環境

必要條件

安裝套件

驗證用戶端

Azure Active Directory

相容性

Web 背景工作

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

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

JavaScript 套件組合

CORS

重要概念

範例

匯入封裝

建立佇列服務用戶端

with DefaultAzureCredential from @azure/identity package

使用連接字串

with StorageSharedKeyCredential

使用SAS令牌

列出此帳戶中的佇列

建立新佇列

將訊息傳送至佇列

瞄核訊息

處理訊息

刪除佇列

疑難排解

後續步驟

參與

意見反應

其他資源

with `DefaultAzureCredential` from `@azure/identity` package

with `StorageSharedKeyCredential`