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

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

概要

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

Queue storage とは

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

Queue サービスの概念

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

• ストレージ アカウント: Azure のストレージにアクセスする場合には必ず、ストレージ アカウントを使用します。 ストレージ アカウントの詳細については、「ストレージ アカウントの概要」を参照してください。

• キュー: キューは、メッセージのセットを格納します。 すべてのメッセージはキューに 格納されている必要があります。 キュー名は小文字で入力する必要があります。 キューの名前付け規則については、「 Naming Queues and Metadata (キューとメタデータの名前付け規則)」を参照してください。

• メッセージ: 形式を問わず、メッセージのサイズは最大で 64 KB です。 メッセージをキューで保持できる最長時間は 7 日間です。 バージョン 2017-07-29 以降では、最大有効期間を任意の正の数にすることができます。また、-1 は、メッセージが期限切れにならないことを示します。 このパラメーターを省略すると、既定の有効期間は 7 日になります。

• URL 形式: キューは次の URL 形式を使って処理できます: http://<storage account>.queue.core.windows.net/<queue>

  次の URL を使用すると、図のいずれかのキューをアドレス指定できます。

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

Azure のストレージ アカウントの作成

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

Azure Storage アカウントは、Azure PowerShell、Azure CLI、または .NET 用 Azure ストレージ リソース プロバイダーを使用して作成することもできます。

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

Node.js アプリケーションの作成

空の Node.js アプリケーションを作成するには、Azure App Service での Node.js Web アプリの作成に関するページ、PowerShell を使用した「Node.js アプリケーションの構築と Azure クラウド サービスへのデプロイ」、または Visual Studio Code に関するページを参照してください。

アプリケーションのストレージへのアクセスの構成

JavaScript 用の Azure Storage クライアント ライブラリに関するページには、ストレージ 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 の既定では、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 段階のプロセスです。

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 秒後に、他のクライアントに表示されます。 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);
}

キューを削除する方法

キューおよびそれに格納されているすべてのメッセージを削除するには、QueueClient オブジェクトの DeleteQueue メソッドを呼び出します。

// 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 クライアント ライブラリのリポジトリにアクセスしてください。