Поделиться через

Клиентская библиотека очереди службы хранилища Azure для JavaScript — версия 12.27.0

Очередь службы хранилища Azure предоставляет облачные сообщения между компонентами приложения. При разработке приложений для масштабирования компоненты приложений часто отделяются, чтобы они могли масштабироваться независимо. Хранилище очередей обеспечивает асинхронное обмен сообщениями между компонентами приложений, независимо от того, работают ли они в облаке, на рабочем столе, на локальном сервере или на мобильном устройстве. Хранилище очередей также поддерживает управление асинхронными задачами и рабочими потоками процесса.

Этот проект предоставляет клиентскую библиотеку в JavaScript, которая упрощает использование службы очередей службы хранилища Azure.

Используйте клиентские библиотеки в этом пакете, чтобы:

  • Получение и задание свойств службы очередей
  • Create/List/Delete Queues
  • Отправка, получение, просмотр, очистка, обновление и удаление сообщений очереди

Key links:

Getting started

Поддерживаемые в настоящее время среды

See our support policy for more details.

Prerequisites

Установка пакета

Предпочтительный способ установки клиентской библиотеки очереди службы хранилища Azure для JavaScript — использовать диспетчер пакетов npm. Введите следующее в окно терминала:

npm install @azure/storage-queue

Проверка подлинности клиента

Служба хранилища Azure поддерживает несколько способов проверки подлинности. Чтобы взаимодействовать со службой хранилища очередей Azure, необходимо создать экземпляр клиента хранилища — QueueServiceClient или QueueClient, например. Дополнительные сведения о проверке подлинности см. в примерах для создания QueueServiceClient.

Azure Active Directory

Служба хранилища очередей Azure поддерживает использование Azure Active Directory для проверки подлинности запросов к своим API. Пакет @azure/identity предоставляет различные типы учетных данных, которые приложение может использовать для этого. Чтобы приступить к работе, ознакомьтесь с README для @azure/identity получения дополнительных сведений и примеров.

Compatibility

Эта библиотека совместима с Node.js и браузерами и проверена на основе версий LTS Node.js (>=8.16.0) и последних версий Chrome, Firefox и Edge.

Web Workers

Эта библиотека требует, чтобы некоторые объекты DOM были глобально доступны при использовании в браузере, которые веб-работники по умолчанию не делают доступными. Эти библиотеки необходимо заполнить, чтобы эта библиотека работала в веб-рабочих нагрузках.

Дополнительные сведения см. в нашей документации по использованию пакета SDK Azure для JS в веб-рабочих

Эта библиотека зависит от следующих API-интерфейсов DOM, которые нуждаются во внешних полизаполнениях, загруженных при использовании в веб-рабочих нагрузках:

Различия между Node.js и браузерами

Существуют различия между средой выполнения Node.js и браузерами. При начале работы с этой библиотекой обратите внимание на API-интерфейсы или классы, помеченные "ТОЛЬКО ДОСТУПНО В СРЕДЕ ВЫПОЛНЕНИЯ NODE.JS" или "ТОЛЬКО ДОСТУПНЫ В БРАУЗЕРАХ".

Следующие функции, интерфейсы, классы или функции доступны только в Node.js
  • Авторизация общего ключа на основе имени учетной записи и ключа учетной записи
    • StorageSharedKeyCredential
  • Создание подписанного URL-адреса (SAS)
    • generateAccountSASQueryParameters()
    • generateQueueSASQueryParameters()

JavaScript Bundle

Чтобы использовать эту клиентную библиотеку в браузере, сначала необходимо использовать пакет. For details on how to do this, please refer to our bundling documentation.

CORS

Необходимо настроить правила совместного использования ресурсов (CORS) для учетной записи хранения, если необходимо разработать для браузеров. Перейдите на портал Azure и обозреватель службы хранилища Azure, найдите свою учетную запись хранения, создайте новые правила CORS для больших двоичных объектов, очередей, файлов и таблиц.

Например, можно создать следующие параметры CORS для отладки. Но настройте параметры тщательно в соответствии с вашими требованиями в рабочей среде.

  • Допустимые источники: *
  • Разрешенные команды: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
  • Разрешенные заголовки: *
  • Открытые заголовки: *
  • Максимальный возраст (в секундах): 86400

Key concepts

Очередь — это хранилище данных в учетной записи службы очередей службы хранилища Azure для отправки и получения сообщений между подключенными клиентами.

Ключевые типы данных в нашей библиотеке, связанные с этими службами:

  • A QueueServiceClient represents a connection (via a URL) to a given storage account in the Azure Storage Queue service and provides APIs for manipulating its queues. Он проходит проверку подлинности в службе и может использоваться для создания объектов QueueClient, а также для создания, удаления, удаления очередей списков из службы.
  • A QueueClient represents a single queue in the storage account. Его можно использовать для управления сообщениями очереди, например для отправки, получения и просмотра сообщений в очереди.

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 из клиентского приложения — 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

    • Роли RBAC для больших двоичных объектов и очередей - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal.
    • На портале Azure перейдите к учетной записи хранения и назначьте участнику данных очереди хранилища роль зарегистрированного приложения AAD на вкладке Access control (IAM) (на левой панели навигации учетной записи хранения на портале Azure).

  • Настройка среды для примера

    • На странице обзора приложения 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

В качестве альтернативы вы создаете экземпляр a QueueServiceClient с StorageSharedKeyCredential помощью прохода accountName и accountKey в качестве аргументов. (Значения имени учетной записи и ключа учетной записи можно получить на портале Azure.) [ДОСТУПНО ТОЛЬКО В 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 с подписанными URL-адресами (SAS). Маркер SAS можно получить на портале Azure или создать его с помощью 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());
}

For a complete sample on iterating queues please see 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}`,
);

A complete example of simple QueueServiceClient scenarios is at samples/v12/typescript/src/queueClient.ts.

Troubleshooting

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения путем вызова setLogLevel в @azure/logger:

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

setLogLevel("info");

Next steps

Дополнительные примеры кода

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

Дополнительные сведения о настройке тестовой среды для библиотек хранилища см. в руководстве по хранилища.