Node.js から Azure Queue Storage を使用する方法

概要

このガイドでは、Azure Queue Storage を使用して一般的なシナリオを実現する方法について説明します。サンプルは、Node.js API を使用して記述されています。対象となるシナリオには、キューメッセージの挿入、確認、取得、削除があります。また、キューを作成および削除する方法についても説明します。

Queue Storage とは

Azure Queue Storage は、HTTP または HTTPS を使用して認証された呼び出しを介して世界中のどこからでもアクセスできる多数のメッセージを格納するためのサービスです。 1 つのキューメッセージのサイズは最大 64 KB で、キューにはストレージアカウントの合計容量制限まで、数百万のメッセージを含めることができます。キューストレージは、非同期的に処理する作業のバックログを作成するためによく使用されます。

キューサービスの概念

Azure Queue サービスには、次のコンポーネントが含まれています。

Azure Queue サービスコンポーネント

#B0 ストレージアカウント: #C1 Azure Storage へのすべてのアクセスは、ストレージアカウントを介して行われます。ストレージアカウントの詳細については、「ストレージアカウントの概要」を参照してください。
キュー: キューは、メッセージのセットを格納します。すべてのメッセージはキューに格納されている必要があります。キュー名は小文字で入力する必要があります。キューの名前付け規則については、「 Naming Queues and Metadata (キューとメタデータの名前付け規則)」を参照してください。
メッセージ: 形式を問わず、メッセージのサイズは最大で 64 KB です。メッセージがキューに残ることができる最大時間は 7 日間です。バージョン 2017-07-29 以降では、最大有効期間を任意の正の数にすることができます。また、-1 は、メッセージが期限切れにならないことを示します。このパラメーターを省略すると、既定の有効期間は 7 日になります。
URL 形式: キューは、次の URL 形式を使用してアドレス指定できます: http://.queue.core.windows.net/<storage account>

次の URL は、図内のキューをアドレス指定します。

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

Azure Storage アカウントを作成する

最初の Azure ストレージアカウントを作成する最も簡単な方法は、Azure portalを使用することです。詳細については、「ストレージアカウントの作成」を参照してください。

Azure PowerShell 、Azure CLI 、または .NET 用Azure Storage Resource Provider使用して、Azure ストレージアカウントを作成することもできます。

現時点で Azure でストレージアカウントを作成しない場合は、Azurite ストレージエミュレーターを使用して、ローカル環境でコードを実行してテストすることもできます。詳細については、「ローカルの Azure Storage 開発に Azurite エミュレーターを使用する」を参照してください。

Node.js アプリケーションを作成する

空の Node.js アプリケーションを作成するには、「Azure App Service で Node.js Web アプリを作成する」を参照してください。PowerShell または Visual Studio Code を使用して、Node.js アプリケーションをビルドして Azure Cloud Services にデプロイします。

ストレージにアクセスするようにアプリケーションを構成する

JavaScript 用 Azure Storage クライアントライブラリには、ストレージ REST サービスと通信する便利なライブラリのセットが含まれています。

Node パッケージマネージャー (npm) を使用してパッケージを取得する

PowerShell (Windows)、ターミナル (Mac)、Bash (Unix) などのコマンドラインインターフェイスを使用して、サンプルアプリケーションを作成したフォルダーに移動します。
コマンドウィンドウに「 npm install @azure/storage-queue 」と入力します。
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 のデフォルトでは、1 つのメッセージを確認します。次の例では、キュー内の最初の 5 つのメッセージを確認します。表示されるメッセージが 5 個未満の場合は、表示されているメッセージだけが返されます。

// 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"
);

メッセージをデキューする方法

メッセージを取り出すプロセスは、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 秒後、他のクライアントに表示されます。 receiveMessagesを呼び出すときにoptions.visibilityTimeoutを設定することで、別の値を指定できます。

キューにメッセージがない場合に receiveMessages を呼び出しても、エラーは返されません。ただし、メッセージは返されません。

メッセージを出列するための追加オプション

キューからのメッセージ取得をカスタマイズする方法は 2 つあります。

options.numberOfMessages: メッセージのバッチを取得します (最大 32)。
options.visibilityTimeout: 非表示タイムアウトを長くまたは短く設定します。

次の例では、 receiveMessages メソッドを使用して、1 回の呼び出しで 5 つのメッセージを取得します。その後、for ループを使用して、各メッセージを処理します。また、このメソッドによって返されるすべてのメッセージの非表示タイムアウトを 5 分に設定します。

// 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 Storage コードサンプルレポジトリを参照してください

ダウンロードして実行できる、使いやすいエンドツーエンドの Azure Storage コードサンプルについては、Azure Storage のサンプルの一覧を確認してください。

次のステップ

Queue Storage の基本を学習したので、これらのリンクに従って、より複雑なストレージタスクについて学習します。

Azure Storage チームのブログにアクセスして、新しい情報を確認してください
GitHub の JavaScript 用 Azure Storage クライアントライブラリにアクセスする

Last updated on 2023-01-20