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

[アーティクル]
05/13/2024

Azure Storage Queue は、アプリケーションコンポーネント間のクラウドメッセージングを提供します。拡張性を重視してアプリケーションを設計する場合、通常、アプリケーションコンポーネントを個別に拡張できるように分離します。 Queue Storage は、アプリケーションコンポーネントがクラウド、デスクトップ、オンプレミスのサーバー、モバイルデバイスのいずれで実行されている場合でも、アプリケーションコンポーネント間の通信に非同期メッセージングを提供します。 Queue Storage ではまた、非同期タスクの管理とプロセスワークフローの構築もサポートします。

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

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

キューサービスのプロパティを取得/設定する
キューのCreate/リスト/削除
キューメッセージの送受信/プレビュー/クリア/更新/削除

主要リンク:

はじめに

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

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

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

前提条件

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

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

npm install @azure/storage-queue

クライアントを認証する

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

Azure Active Directory
共有キー
共有アクセス署名

Azure Active Directory

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

互換性

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

Web Worker

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

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

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

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

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

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

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

JavaScript バンドル

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

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 、ストレージアカウント内の 1 つの キュー を表します。キュー内のメッセージの送信、受信、ピークなど、キューのメッセージを操作するために使用できます。

例

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

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

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 アプリケーションの概要ページで、と TENANT IDをCLIENT IDメモします。 [Certificates & Secrets]\(証明書 & シークレット\) タブで、シークレットを作成し、下にメモします。
- サンプルをAZURE_TENANT_ID正常に実行するための環境変数として、 AZURE_CLIENT_IDAZURE_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);

with `StorageSharedKeyCredential`

または、account-name と account-key を引数として渡すことによって、を使用してをインスタンス化QueueServiceClientStorageSharedKeyCredentialします。 (アカウント名とアカウントキーは、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 トークンを使用する

また、Shared Access Signature (SAS) を使用してをインスタンス化 QueueServiceClient することもできます。 Azure Portal から SAS トークンを取得するか、を使用して SAS トークンを 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}`
);

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

関数を使用して、新しいfor-await-of構文を使用QueueServiceClient.listQueues()してキューを反復処理します。

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() {
  let 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() {
  let 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() では、キューの前にある 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 に設定します。または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

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

setLogLevel("info");

次のステップ

その他のコードサンプル

共同作成

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

ストレージライブラリのテスト環境を設定する方法の詳細については、「ストレージ固有のガイド」も参照してください。

インプレッション数

次の方法で共有

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

はじめに

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

前提条件

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

クライアントを認証する

Azure Active Directory

互換性

Web Worker

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

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

JavaScript バンドル

CORS

主要な概念

例

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

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

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

接続文字列の使用

with `StorageSharedKeyCredential`

SAS トークンを使用する

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

新しいキューを作成する

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

メッセージをクイック表示する

メッセージの処理

キューを削除する

トラブルシューティング

次のステップ

共同作成

フィードバック

その他のリソース

次の方法で共有

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

はじめに

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

前提条件

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

クライアントを認証する

Azure Active Directory

互換性

Web Worker

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

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

JavaScript バンドル

CORS

主要な概念

例

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

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

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

接続文字列の使用

with StorageSharedKeyCredential

SAS トークンを使用する

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

新しいキューを作成する

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

メッセージをクイック表示する

メッセージの処理

キューを削除する

トラブルシューティング

次のステップ

共同作成

フィードバック

その他のリソース

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

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

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

with `StorageSharedKeyCredential`