你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 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。请参阅示例，了解如何创建 QueueServiceClient，了解有关身份验证的详细信息。

Azure Active Directory
共享密钥
共享访问签名

Azure Active Directory

Azure 队列存储服务支持使用 Azure Active Directory 对其 API 的请求进行身份验证。 @azure/identity 包提供了应用程序可用于执行此操作的各种凭据类型。有关更多详细信息和示例，请参阅自述文件以获取更多详细信息和示例。

兼容性

此库与 Node.js 和浏览器兼容，并针对 LTS Node.js 版本（>=8.16.0）和最新版本的 Chrome、Firefox 和 Edge 进行验证。

Web 辅助角色

此库要求某些 DOM 对象在浏览器中使用时全局可用，Web 辅助角色默认不提供这些对象。需要填充这些内容以使此库在 Web 辅助角色中正常工作。

有关详细信息，请参阅我们的文档，了解如何在 Web 辅助角色中使用 Azure SDK for JS

此库依赖于以下 DOM API，这些 API 需要在 Web 辅助角色中使用时加载外部填充：

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 存储队列服务中给定 存储帐户 的连接（通过 URL），并提供用于操作队列的 API。它向服务进行身份验证，可用于创建 QueueClient 对象，以及从服务创建、删除、列出队列。
QueueClient 表示存储帐户中的单个队列。它可用于操作队列的消息，例如在队列中发送、接收和查看消息。

例子

导入包

若要使用客户端，请将包导入文件：

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

或者，选择性地仅导入所需的类型：

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

创建队列服务客户端

QueueServiceClient 需要队列服务和访问凭据的 URL。它还可以选择接受 options 参数中的某些设置。

包含来自 `DefaultAzureCredential` 包的 `@azure/identity`

实例化 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 门户中，转到存储帐户，并从 azure 门户的存储帐户左侧导航栏中，将 存储队列数据参与者 角色分配给已注册的 AAD Access control (IAM) 应用程序。
示例的环境设置
- 在 AAD 应用程序的概述页中，记下 CLIENT ID 和 TENANT ID。在“证书 & 机密”选项卡中，创建机密并记下。
- 请确保 AZURE_TENANT_ID、AZURE_CLIENT_IDAZURE_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]

使用连接字符串

或者，可以使用具有完整连接字符串作为参数的 QueueServiceClient 静态方法实例化 fromConnectionString()。（可以从 Azure 门户获取连接字符串。[仅在 NODE.JS RUNTIME 中可用]

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

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

with `StorageSharedKeyCredential`

或者，通过将帐户名称和帐户密钥作为参数传递来实例化具有 QueueServiceClient 的 StorageSharedKeyCredential。（可以从 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 令牌

此外，还可以使用共享访问签名（SAS）实例化 QueueServiceClient。可以从 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");

后续步骤

更多代码示例

贡献

若要参与此库，请阅读贡献指南了解有关如何生成和测试代码的详细信息。

另请参阅存储特定指南，了解有关为存储库设置测试环境的其他信息。

通过