Использование Хранилища очередей Azure из Node.js

• .NET
• Java
• Python
• Node.js
• C++
• Ruby
• PHP

Обзор

В этом руководстве показано, как реализовать типичные сценарии использования службы "Хранилище очередей Azure". Примеры написаны с использованием интерфейса API Node.js. Рассматриваемые сценарии включают вставку, просмотр, получение и удаление сообщений очереди. Также узнайте, как создавать и удалять очереди.

Что такое хранилище очередей?

Хранилище очередей Azure — это служба для хранения большого количества сообщений, к которым можно получить доступ практически из любой точки мира с помощью вызовов с проверкой подлинности по протоколам HTTP или HTTPS. Одно сообщение очереди может быть размером до 64 КБ, а очередь может содержать миллионы сообщений до общего ограничения емкости учетной записи хранения. Хранилище очередей часто используется для создания списка невыполненных заданий для асинхронной обработки.

Основные понятия службы очередей

Служба очередей Azure содержит следующие компоненты:

• Учетная запись хранения. Весь доступ к хранилищу Azure осуществляется с помощью учетной записи хранения. См. сведения об учетных записях хранения.

• Очередь. Очередь содержит набор сообщений. Все сообщения должны находиться в очереди. Обратите внимание: имя очереди должно содержать только строчные символы. Дополнительные сведения см. в статье о присвоении имен очередям и метаданным.

• Сообщение. Сообщение в любом формате размером до 64 КБ. Сообщение может оставаться в очереди не более 7 дней. Начиная с версии 2017-07-29, максимальный срок жизни может быть задан любым положительным числом или значением -1, свидетельствующим о том, что срок жизни сообщения неограничен. Если этот параметр не указан, срок жизни по умолчанию составляет семь дней.

• Формат URL-адреса: обращаться к очередям можно с помощью URL-адреса следующего вида: http://<storage account>.queue.core.windows.net/<queue>

  Следующий URL-адрес позволяет обратиться к очереди на схеме:

  http://myaccount.queue.core.windows.net/incoming-orders

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

Самый простой способ создать первую учетную запись хранения Azure — воспользоваться порталом Azure. Дополнительную информацию см. в статье Об учетных записях хранения Azure.

Кроме того, создать учетную запись хранения Azure можно с помощью Azure PowerShell, Azure CLI или поставщика ресурсов службы хранилища Azure для .NET.

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

Создание приложения Node.js

Инструкции по созданию пустого приложения Node.js см. в разделах Создание веб-приложения Node.js в Службе приложений Azure и Построение и развертывание приложения Node.js в Облачных службах Azure с использованием PowerShell или Visual Studio Code.

Настройка приложения для доступа к хранилищу

Клиентская библиотека службы хранилища Azure для JavaScript содержит набор удобных библиотек, взаимодействующих со службами REST службы хранилища.

Использование диспетчера пакетов Node (NPM) для получения пакета

1. Используя интерфейс командной строки, например PowerShell (Windows), Terminal (Mac) или Bash (Unix), перейдите в папку, в которой создан пример приложения.

2. Введите npm install @azure/storage-queue в командном окне.

3. Убедитесь, что папка node_modules создана. В этой папке находится пакет @azure/storage-queue, содержащий клиентские библиотеки, необходимые для доступа к хранилищу.

Импорт пакета

Используя редактор кода, добавьте следующий код в начало файла JavaScript, где планируется использовать очереди.

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

Как создать очередь

Следующий код получает значение переменной среды с именем AZURE_STORAGE_CONNECTION_STRING и использует ее для создания объекта QueueServiceClient. Затем этот объект используется для создания объекта QueueClient, который позволяет работать с определенной очередью.

// Retrieve the connection from an environment
// variable called AZURE_STORAGE_CONNECTION_STRING
const connectionString = process.env.AZURE_STORAGE_CONNECTION_STRING;

// Create a unique name for the queue
const queueName = "myqueue-" + Date.now().toString();

console.log("Creating queue: ", queueName);

// Instantiate a QueueServiceClient which will be used
// to create a QueueClient and to list all the queues
const queueServiceClient = QueueServiceClient.fromConnectionString(connectionString);

// Get a QueueClient which will be used
// to create and manipulate a queue
const queueClient = queueServiceClient.getQueueClient(queueName);

// Create the queue
await queueClient.create();

Если очередь уже существует, порождается исключение.

Форматирование сообщения

Тип сообщения — строка. Все сообщения обрабатываются как строки. Если необходимо отправить другой тип данных, необходимо сериализовать этот тип данных в строку при отправке сообщения и десериализовать формат строки при чтении сообщения.

Чтобы преобразовать JSON в строковый формат и обратно в Node.js, используйте следующие вспомогательные функции:

function jsonToBase64(jsonObj) {
    const jsonString = JSON.stringify(jsonObj)
    return  Buffer.from(jsonString).toString('base64')
}
function encodeBase64ToJson(base64String) {
    const jsonString = Buffer.from(base64String,'base64').toString()
    return JSON.parse(jsonString)
}

Вставка сообщения в очередь

Чтобы добавить сообщение в очередь, вызовите метод sendMessage.

messageText = "Hello, World";
console.log("Adding message to the queue: ", messageText);

// Add a message to the queue
await queueClient.sendMessage(messageText);

Как посмотреть следующее сообщение

Вы можете просматривать сообщения в очереди, не удаляя их из очереди, путем вызова метода peekMessages.

По умолчанию peekMessages просматривает одно сообщение. В следующем примере просматриваются первые пять сообщений в очереди. Если отображается менее пяти сообщений, возвращаются только видимые сообщения.

// Peek at messages in the queue
const peekedMessages = await queueClient.peekMessages({ numberOfMessages: 5 });

for (i = 0; i < peekedMessages.peekedMessageItems.length; i++) {
    // Display the peeked message
    console.log("Peeked message: ", peekedMessages.peekedMessageItems[i].messageText);
}

Если в очереди нет сообщений, вызов peekMessages не возвращает ошибку. Но и сообщения не возвращаются.

Как изменить содержимое сообщения в очереди

В следующем примере обновляется текст сообщения.

Вы можете изменить содержимое сообщения непосредственно в очереди путем вызова updateMessage.

// Get the first message in the queue
var receivedMessages = await queueClient.receiveMessages();
const firstMessage = receivedMessages.receivedMessageItems[0];

// Update the received message
await queueClient.updateMessage(
    firstMessage.messageId,
    firstMessage.popReceipt,
    "This message has been updated"
);

Как удалить сообщение из очереди

Удаление сообщения из очереди выполняется в два этапа:

1. получение сообщения;

2. удаление сообщения.

В следующем примере сообщение сначала извлекается, а затем удаляется.

Чтобы получить сообщение, вызовите метод receiveMessages. Вызов этого метода делает сообщение невидимым в очереди, и другие клиенты не могут его обрабатывать. После того как ваше приложение обработает сообщение, вызовите метод deleteMessage, чтобы удалить его из очереди.

// Get next message from the queue
receivedMessages = await queueClient.receiveMessages();
var message = receivedMessages.receivedMessageItems[0];

console.log("Dequeuing message: ", message.messageText);

await queueClient.deleteMessage(message.messageId, message.popReceipt);

По умолчанию сообщение скрывается только на 30 секунд. Через 30 секунд оно станет видимым для других клиентов. Вы можете указать другое значение, задав options.visibilityTimeout при вызове метода receiveMessages.

Если в очереди нет сообщений, вызов receiveMessages не возвращает ошибку. Но и сообщения не будут возвращены.

Дополнительные варианты удаления сообщений из очереди

Существует два способа настройки извлечения сообщения из очереди:

• options.numberOfMessages: извлекает пакет сообщений (до 32).
• options.visibilityTimeout: задает другой временной интервал невидимости.

В следующем примере используется метод receiveMessages для получения 5 сообщений за один вызов. Затем он обрабатывает каждое сообщение с помощью цикла for. Он также задает время ожидания невидимости пять минут для всех сообщений, возвращенных методом.

// Get up to 5 messages from the queue
const receivedMsgsResp = await queueClient.receiveMessages({ numberOfMessages: 5, visibilityTimeout: 5 * 60 });

for (i = 0; i < receivedMsgsResp.receivedMessageItems.length; i++)
{
    message = receivedMsgsResp.receivedMessageItems[i];
    console.log("Dequeuing message: ", message.messageText);
    await queueClient.deleteMessage(message.messageId, message.popReceipt);
}

Как получить длину очереди

Метод getProperties возвращает метаданные очереди, в том числе приблизительное количество сообщений, ожидающих в очереди.

const properties = await queueClient.getProperties();
console.log("Approximate queue length: ", properties.approximateMessagesCount);

Как получить список очередей

Чтобы получить список очередей, вызовите QueueServiceClient.listQueues. Чтобы получить список, отфильтрованный по определенному префиксу, задайте options.prefix в вызове listQueues.

for await (const item of queueServiceClient.listQueues()) {
  console.log("Queue: ", item.name);
}

Удаление очереди

Чтобы удалить очередь и все сообщения в ней, вызовите метод DeleteQueue для объекта QueueClient.

// Delete the queue
console.log("Deleting queue: ", queueClient.name);
await queueClient.delete();

Чтобы удалить все сообщения в очереди без удаления самой очереди, вызовите ClearMessages.

Совет

См. примеры кода в репозитории службы хранилища Azure

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

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

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

• Посетите блог команды разработчиков службы хранилища Azure, чтобы узнать о новых возможностях
• Посетите репозиторий клиентской библиотеки службы хранилища Azure для JavaScript на GitHub