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

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

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

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

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

Ключевые ссылки:

• исходный код.
• Пакет (npm)
• Справочная документация по API
• документации по продукту
• Примеры
• REST API очереди службы хранилища Azure

Начало работы

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

• LTS версии Node.js
• Последние версии Safari, Chrome, Edge и Firefox.

Дополнительные сведения см. в политике поддержки .

Необходимые условия

• подписки Azure
• учетной записи хранения

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

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

npm install @azure/storage-queue

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

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

• Azure Active Directory
• общий ключ
• подписей общего доступа

Azure Active Directory

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

Совместимость

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

Веб-рабочие роли

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

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

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

• document
• DOMParser
• Node
• XMLSerializer

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

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

Следующие функции, интерфейсы, классы или функции доступны только в Node.js

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

Пакет JavaScript

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

CORS

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

Например, можно создать следующие параметры 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.

с DefaultAzureCredential из пакета @azure/identity

Рекомендуемый способ создания экземпляра QueueServiceClient

Настройка. Справочник. Авторизация доступа к blob-объектам и очередям с помощью Azure Active Directory из клиентского приложения — /azure/storage/common/storage-auth-aad-app

• Регистрация нового приложения AAD и предоставление разрешений на доступ к службе хранилища Azure от имени вошедшего пользователя

  • Регистрация нового приложения в Azure Active Directory (на портале Azure) — /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 для больших двоичных объектов и очередей — /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).

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]

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

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

с StorageSharedKeyCredential

Кроме того, вы создаете экземпляр QueueServiceClient с StorageSharedKeyCredential путем передачи имени учетной записи и ключа учетной записи в качестве аргументов. (Имя учетной записи и ключ учетной записи можно получить на портале 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 с подписанными URL-адресами (SAS). Маркер SAS можно получить на портале Azure или создать его с помощью 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 секунд.
• При обработке сообщения вызовите queueClient.deleteMessage() с popReceiptсообщения.

Если код не может обработать сообщение из-за сбоя оборудования или программного обеспечения, этот двухэтапный процесс гарантирует, что другой экземпляр кода может получить то же сообщение и повторить попытку.

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 приведен в примерах/v12/typescript/src/queueClient.ts.

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

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

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

setLogLevel("info");

Дальнейшие действия

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

• Примеры хранилища очередей
• тестовые случаи хранилища очередей

Способствует

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по вкладу, чтобы узнать больше о том, как создавать и тестировать код.

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