JavaScript 用 Azure Storage Queue クライアントライブラリ - バージョン 12.25.0

[アーティクル]
11/20/2024

Azure Storage Queue は、アプリケーションコンポーネント間のクラウドメッセージングを提供します。アプリケーションをスケール用に設計する場合、アプリケーションコンポーネントは個別にスケーリングできるように分離されることがよくあります。 Queue Storage は、アプリケーションコンポーネントがクラウド、デスクトップ、オンプレミスサーバー、モバイルデバイスのどちらで実行されているかに関係なく、アプリケーションコンポーネント間の通信に非同期メッセージングを提供します。キューストレージでは、非同期タスクの管理とプロセスワークフローの構築もサポートされています。

このプロジェクトは、Azure Storage Queue サービスを簡単に使用できる JavaScript のクライアントライブラリを提供します。

このパッケージのクライアントライブラリを使用して、次の操作を行います。

キューサービスのプロパティを取得/設定する
キューの作成/一覧表示/削除
キューメッセージの送受信/ピーク/クリア/更新/削除

主要なリンク:

ソースコードの
パッケージ (npm)
API リファレンスドキュメント
製品のドキュメント
サンプル
Azure Storage Queue REST API をする

はじめ

現在サポートされている環境

Node.js の LTS バージョンをする
Safari、Chrome、Edge、Firefox の最新バージョン。

詳細については、サポートポリシーのを参照してください。

前提条件

パッケージをインストールする

JavaScript 用の Azure Storage Queue クライアントライブラリをインストールする推奨される方法は、npm パッケージマネージャーを使用することです。ターミナルウィンドウに次のように入力します。

npm install @azure/storage-queue

クライアントを認証する

Azure Storage では、いくつかの認証方法がサポートされています。 Azure Queue Storage サービスと対話するには、ストレージクライアントのインスタンス (QueueServiceClient や QueueClient など) を作成する必要があります。認証の詳細については、の作成に関するサンプルを参照してください。

Azure Active Directory
共有キーの
Shared Access Signature

Azure Active Directory

Azure Queue Storage サービスでは、Azure Active Directory を使用して API への要求を認証できます。 @azure/identity パッケージには、アプリケーションでこれを行うために使用できるさまざまな資格情報の種類が用意されています。作業を開始するための詳細とサンプルについては、の README を参照してください。

互換性

このライブラリは、Node.js とブラウザーと互換性があり、LTS Node.js バージョン (>=8.16.0) と Chrome、Firefox、Edge の最新バージョンに対して検証されます。

Web Worker

このライブラリでは、ブラウザーで使用する場合、特定の DOM オブジェクトをグローバルに使用できる必要があります。Web ワーカーは既定では使用できません。 Web ワーカーでこのライブラリを動作させるには、これらをポリフィルする必要があります。

詳細については、Web Worker で Azure SDK for JS を使用するためのドキュメントを参照してください

このライブラリは、Web ワーカーで使用するときに外部ポリフィルを読み込む必要がある次の DOM API に依存します。

Node.js とブラウザーの違い

Node.js とブラウザーのランタイムには違いがあります。このライブラリの使用を開始するときは、"ONLY AVAILABLE IN NODE.JS RUNTIME" または "ONLY AVAILABLE IN BROWSERS"でマークされた API またはクラスに注意してください。

次の機能、インターフェイス、クラス、または関数は、Node.js でのみ使用できます

アカウント名とアカウントキーに基づく共有キーの承認
- StorageSharedKeyCredential
Shared Access Signature (SAS) の生成
- generateAccountSASQueryParameters()
- generateQueueSASQueryParameters()

JavaScript バンドル

ブラウザーでこのクライアントライブラリを使用するには、まず、バンドルを使用する必要があります。これを行う方法の詳細については、バンドルドキュメントを参照してください。

CORS

ブラウザー用に開発する必要がある場合は、ストレージアカウントクロスオリジンリソース共有 (CORS) 規則を設定する必要があります。 Azure portal と Azure Storage Explorer に移動し、ストレージアカウントを見つけ、BLOB/キュー/ファイル/テーブルサービス用の新しい CORS ルールを作成します。

たとえば、デバッグ用に次の CORS 設定を作成できます。ただし、運用環境の要件に合わせて設定を慎重にカスタマイズしてください。

許可される配信元: *
使用できる動詞: DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
許可されるヘッダー: *
公開されたヘッダー: *
最長有効期間 (秒): 86400

主な概念

キューは、接続されたクライアント間でメッセージを送受信するための Azure Storage Queue サービスアカウント内のデータストアです。

これらのサービスに関連するライブラリの主なデータ型は次のとおりです。

QueueServiceClient は、Azure Storage Queue サービス内の特定の ストレージアカウント への接続 (URL 経由) を表し、そのキューを操作するための API を提供します。これはサービスに対して認証され、QueueClient オブジェクトの作成や、サービスからのキューの作成、削除、一覧表示に使用できます。
QueueClient は、ストレージアカウント内の単一の キュー を表します。キュー内のメッセージの送信、受信、ピークなど、キューのメッセージを操作するために使用できます。

例

パッケージをインポートする

クライアントを使用するには、パッケージをファイルにインポートします。

const AzureStorageQueue = require("@azure/storage-queue");

または、必要な型のみを選択的にインポートします。

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

キューサービスクライアントを作成する

QueueServiceClient には、キューサービスへの URL とアクセス資格情報が必要です。また、必要に応じて、options パラメーターの一部の設定を受け入れます。

パッケージからの `DefaultAzureCredential@azure/identity` 使用

QueueServiceClient をインスタンス化するための推奨される方法

セットアップ : リファレンス - クライアントアプリケーションから Azure Active Directory を使用して BLOB とキューへのアクセスを承認する - /azure/storage/common/storage-auth-aad-app

新しい AAD アプリケーションを登録し、サインインしているユーザーの代わりに Azure Storage にアクセスするためのアクセス許可を付与する
- Azure Active Directory (azure-portal) に新しいアプリケーションを登録する - /azure/active-directory/develop/quickstart-register-app
- [API permissions] セクションで、[Add a permission] を選択し、[Microsoft APIs] を選択します。
- Azure Storage を選択し、[user_impersonation] の横にあるチェックボックスをオンにして、[Add permissions] をクリックします。これにより、アプリケーションはサインインしているユーザーの代わりに Azure Storage にアクセスできるようになります。
Azure Portal で RBAC を使用して Azure Storage Queue データへのアクセスを許可する
- BLOB とキューの RBAC ロール - /azure/storage/common/storage-auth-aad-rbac-portal。
- Azure portal でストレージアカウントに移動し、ストレージキューデータ共同作成者の ロールを、(azure-portal のストレージアカウントの左側のナビゲーションバーにある) Access control (IAM) タブから登録済みの AAD アプリケーションに割り当てます。
サンプルの環境のセットアップ
- 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専用です]

接続文字列の使用

または、完全な接続文字列を引数として使用して、fromConnectionString() 静的メソッドを使用して QueueServiceClient をインスタンス化することもできます。 (接続文字列は Azure portal から取得できます)。[NODE.JS ランタイムでのみ使用可能]

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

const connStr = "<connection string>";

const queueServiceClient = QueueServiceClient.fromConnectionString(connStr);

`StorageSharedKeyCredential`

または、アカウント名とアカウントキーを引数として渡すことによって、StorageSharedKeyCredential を使用して QueueServiceClient をインスタンス化します。 (アカウント名とアカウントキーは、Azure portal から取得できます)。[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 トークンを使用する

また、共有アクセス署名 (SAS) を使用して QueueServiceClient をインスタンス化することもできます。 Azure Portal から SAS トークンを取得することも、generateAccountSASQueryParameters()を使用して SAS トークンを生成することもできます。

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();

キューの反復処理の完全なサンプルについては、サンプル/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() では、キューの前にある 1 つ以上のメッセージを確認できます。この呼び出しでは、他のコードがピークされたメッセージにアクセスすることを防ぐことはありません。

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();

メッセージの処理

メッセージは 2 つの手順で処理されます。

最初の呼び出し queueClient.receiveMessages(). これにより、既定の 30 秒間、このキューからメッセージを読み取る他のコードからメッセージが非表示になります。
メッセージの処理が完了したら、メッセージの popReceiptで queueClient.deleteMessage() を呼び出します。

ハードウェアまたはソフトウェアの障害が原因でコードがメッセージを処理できない場合、この 2 段階のプロセスにより、コードの別のインスタンスが同じメッセージを取得して再試行できるようになります。

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 シナリオの完全な例は、samples/v12/typescript/src/queueClient.tsにあります。

トラブルシューティング

ログ記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、AZURE_LOG_LEVEL 環境変数を infoに設定します。または、setLogLevelで @azure/logger を呼び出すことによって、実行時にログを有効にすることもできます。

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

setLogLevel("info");

次の手順

その他のコードサンプル

貢献

このライブラリに投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

また、ストレージライブラリのテスト環境の設定に関する追加情報については、Storage 固有のガイドのを参照してください。

インプレッション

次の方法で共有

JavaScript 用 Azure Storage Queue クライアントライブラリ - バージョン 12.25.0

はじめ

現在サポートされている環境

前提条件

パッケージをインストールする

クライアントを認証する

Azure Active Directory

互換性

Web Worker

Node.js とブラウザーの違い

次の機能、インターフェイス、クラス、または関数は、Node.js でのみ使用できます

JavaScript バンドル

CORS

主な概念

例

パッケージをインポートする

キューサービスクライアントを作成する

パッケージからの `DefaultAzureCredential@azure/identity` 使用

接続文字列の使用

`StorageSharedKeyCredential`

SAS トークンを使用する

このアカウントのキューを一覧表示する

新しいキューを作成する

キューにメッセージを送信する

メッセージをピークする

メッセージの処理

キューを削除する

トラブルシューティング

次の手順

貢献

その他のリソース

次の方法で共有

JavaScript 用 Azure Storage Queue クライアント ライブラリ - バージョン 12.25.0

はじめ

現在サポートされている環境

前提 条件

パッケージをインストールする

クライアントを認証する

Azure Active Directory

互換性

Web Worker

Node.js とブラウザーの違い

次の機能、インターフェイス、クラス、または関数は、Node.js でのみ使用できます

JavaScript バンドル

CORS

主な概念

例

パッケージをインポートする

キュー サービス クライアントを作成する

パッケージからの DefaultAzureCredential@azure/identity 使用

接続文字列の使用

StorageSharedKeyCredential

SAS トークンを使用する

このアカウントのキューを一覧表示する

新しいキューを作成する

キューにメッセージを送信する

メッセージをピークする

メッセージの処理

キューを削除する

トラブルシューティング

次の手順

貢献

その他のリソース

JavaScript 用 Azure Storage Queue クライアントライブラリ - バージョン 12.25.0

前提条件

キューサービスクライアントを作成する

パッケージからの `DefaultAzureCredential@azure/identity` 使用

`StorageSharedKeyCredential`