クイックスタート: Java 用 Azure Queue Storage クライアント ライブラリ

Java 用 Azure Queue Storage クライアント ライブラリを使用してみましょう。 Azure Queue Storage は、後で取得して処理するために多数のメッセージを格納するためのサービスです。 以下の手順に従って、パッケージをインストールし、基本タスクのコード例を試してみましょう。

API リファレンスのドキュメント | ライブラリのソース コード | パッケージ (Maven) | サンプル

Java 用 Azure Queue Storage クライアント ライブラリを使用すると、以下のことができます。

  • キューを作成する
  • メッセージをキューに追加する
  • キュー内のメッセージを表示する
  • キュー内のメッセージを更新する
  • キューの長さを取得する
  • キューからメッセージを受信する
  • キューからメッセージを削除する
  • キューを削除する

前提条件

設定

このセクションでは、Java 用 Azure Queue Storage クライアント ライブラリを操作するためのプロジェクトの準備について説明します。

プロジェクトを作成する

queues-quickstart という名前の Java アプリケーションを作成します。

  1. コンソール ウィンドウ (cmd、PowerShell、Bash など) で、Maven を使用し、queues-quickstart という名前で新しいコンソール アプリを作成します。 次の mvn コマンドを入力して "Hello, world!" Java プロジェクトを作成します。

    mvn archetype:generate `
        --define interactiveMode=n `
        --define groupId=com.queues.quickstart `
        --define artifactId=queues-quickstart `
        --define archetypeArtifactId=maven-archetype-quickstart `
        --define archetypeVersion=1.4
    
  2. プロジェクトの生成からの出力は、次のようになります。

    [INFO] Scanning for projects...
    [INFO]
    [INFO] ------------------< org.apache.maven:standalone-pom >-------------------
    [INFO] Building Maven Stub Project (No POM) 1
    [INFO] --------------------------------[ pom ]---------------------------------
    [INFO]
    [INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>>
    [INFO]
    [INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<<
    [INFO]
    [INFO]
    [INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom ---
    [INFO] Generating project in Batch mode
    [INFO] ----------------------------------------------------------------------------
    [INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
    [INFO] ----------------------------------------------------------------------------
    [INFO] Parameter: groupId, Value: com.queues.quickstart
    [INFO] Parameter: artifactId, Value: queues-quickstart
    [INFO] Parameter: version, Value: 1.0-SNAPSHOT
    [INFO] Parameter: package, Value: com.queues.quickstart
    [INFO] Parameter: packageInPathFormat, Value: com/queues/quickstart
    [INFO] Parameter: version, Value: 1.0-SNAPSHOT
    [INFO] Parameter: package, Value: com.queues.quickstart
    [INFO] Parameter: groupId, Value: com.queues.quickstart
    [INFO] Parameter: artifactId, Value: queues-quickstart
    [INFO] Project created from Archetype in dir: C:\quickstarts\queues\queues-quickstart
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time:  6.394 s
    [INFO] Finished at: 2019-12-03T09:58:35-08:00
    [INFO] ------------------------------------------------------------------------
    
  3. 新しく作成された queues-quickstart ディレクトリに切り替えます。

    cd queues-quickstart
    

パッケージのインストール

テキスト エディターで pom.xml ファイルを開きます。

azure-sdk-bom を追加して、最新バージョンのライブラリへの依存関係を設定します。 次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 azure-sdk-bom を使用すると、個々の依存関係のバージョンを指定する必要がなくなります。 BOM の詳細については、AZURE SDK BOM に関するページを参照してください。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

その後、依存関係のグループに、次の dependency 要素を追加します。 Azure サービスへのパスワードレス接続には、azure-identity 依存関係が必要です。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-queue</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

アプリのフレームワークを設定する

プロジェクト ディレクトリで次の操作を行います。

  1. /src/main/java/com/queues/quickstart ディレクトリに移動します
  2. 使用しているエディターで App.java ファイルを開きます
  3. System.out.println("Hello, world"); ステートメントを削除します
  4. import ディレクティブを追加します

コードは次のとおりです。

package com.queues.quickstart;

/**
 * Azure Queue Storage client library quickstart
 */
import com.azure.identity.*;
import com.azure.storage.queue.*;
import com.azure.storage.queue.models.*;
import java.io.*;

public class App
{
    public static void main(String[] args) throws IOException
    {
        // Quickstart code goes here
    }
}

Azure に対して認証します

ほとんどの Azure サービスに対するアプリケーション要求は、認可される必要があります。 コード内の Azure サービスに対してパスワードレス接続を実装するには、Azure ID クライアント ライブラリによって提供される DefaultAzureCredential クラスを使用する方法お勧めします。

パスワード、接続文字列、その他の資格情報を使用して、Azure サービスへの要求を直接承認することもできます。 ただし、この方法は慎重に使用する必要があります。 開発者は、安全でない場所にこれらのシークレットを公開しないように注意する必要があります。 パスワードまたはシークレット キーへのアクセス権を取得したユーザーは、誰でも認証を受けることができます。 DefaultAzureCredential はアカウント・キーよりも管理しやすく、セキュリティが優れており、パスワードレス認証が可能になります。 両方のオプションの例を次に示します。

DefaultAzureCredential は、Java 用 Azure Identity クライアント ライブラリによって提供されるクラスです。 DefaultAzureCredential の詳細については、DefaultAzureCredential の概要を参照してください。 DefaultAzureCredential は複数の認証方法をサポートしており、実行時に使用する方法が決定されます。 このアプローチを採用すると、環境固有のコードを実装することなく、異なる環境 (ローカルと運用環境) で異なる認証方法をアプリに使用できます。

たとえば、ローカルでの開発時には Azure CLI サインイン資格情報を使ってアプリを認証し、それが Azure にデプロイされたらマネージド ID を使用できます。 この移行のためにコードを変更する必要はありません。

ローカルで開発する場合は、キュー データにアクセスするユーザー アカウントに正しいアクセス許可があることを確認します。 キュー データの読み取りと書き込みを行うには、ストレージ キュー データ共同作成者が必要です。 このロールを自分に割り当てるには、ユーザー アクセス管理者ロール、または Microsoft.Authorization/roleAssignments/write アクションを含む別のロールに割り当てられている必要があります。 Azure portal、Azure CLI、または Azure PowerShell を使用して、ユーザーに Azure RBAC ロールを割り当てることができます。 ロールの割り当てに使用できるスコープの詳細は、スコープの概要ページでご覧いただけます。

このシナリオでは、最小限の特権の原則に従って、ストレージ アカウントに限定したアクセス許可をユーザー アカウントに割り当てます。 この方法を使って、ユーザーに必要最小限のアクセス許可のみを与え、より安全な運用環境を作成します。

次の例では、ストレージ キュー データ共同作成者ロールを自分のユーザー アカウントに割り当てます。これにより、そのストレージ アカウント内のキュー データに対する読み取りと書き込みの両方のアクセス権が付与されます。

重要

ほとんどの場合、ロールの割り当てが Azure に反映されるまでの時間は 1 分から 2 分ですが、まれに 8 分程度までかかる場合があります。 初めてコードを実行したときに認証エラーを受け取る場合は、しばらく待ってから再試行してください。

  1. Azure portal で、メインの検索バーまたは左側のナビゲーションを使ってストレージ アカウントを見つけます。

  2. ストレージ アカウントの概要ページで、左側のメニューから [アクセス制御 (IAM)] を選びます。

  3. [アクセス制御 (IAM)] ページで、[ロールの割り当て] タブを選びます。

  4. 上部のメニューから [+ 追加] を選択し、次に結果のドロップダウン メニューから [ロールの割り当ての追加] を選択します。

A screenshot showing how to assign a role.

  1. 検索ボックスを使って、結果を目的のロールに絞り込みます。 この例では、「ストレージ キュー データ共同作成者」を検索し、一致する結果を選び、[次へ] を選びます。

  2. [アクセスの割り当て先] で、[ユーザー、グループ、またはサービス プリンシパル] を選び、[+ メンバーの選択] を選びます。

  3. ダイアログで、自分の Microsoft Entra ユーザー名 (通常は user@domain メール アドレス) を検索し、ダイアログの下部にある [選択] を選びます。

  4. [レビューと割り当て] を選んで最終ページに移動し、もう一度 [レビューと割り当て] を行ってプロセスを完了します。

オブジェクト モデル

Azure Queue storage は、多数のメッセージを格納するためのサービスです。 キュー メッセージの許容される最大サイズは 64 KB です。 キューには、ストレージ アカウントの総容量の上限を超えない限り、数百万のメッセージを含めることができます。 キューは通常、非同期的な処理用に作業のバックログを作成するために使用されます。 Queue Storage には、次の 3 種類のリソースがあります。

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

次の図に、これらのリソースの関係を示します。

Diagram of Queue storage architecture

これらのリソースとやり取りするには、以下の Java クラスを使用します。

  • QueueClientBuilder: QueueClientBuilder クラスは、QueueClient オブジェクトを構成し、インスタンス化します。
  • QueueServiceClient: QueueServiceClient を使用すると、ストレージ アカウント内のすべてのキューを管理できます。
  • QueueClient: QueueClient クラスを使用すると、個々のキューとそのメッセージを管理および操作できます。
  • QueueMessageItem: QueueMessageItem クラスは、キューに対して ReceiveMessages を呼び出したときに返される個々のオブジェクトを表します。

コード例

以下のサンプル コード スニペットは、Java 用 Azure Queue Storage クライアント ライブラリを使用して以下の操作を実行する方法を示します。

アクセスの認可とクライアント オブジェクトの作成

ロールを割り当てたのと同じ Microsoft Entra アカウントで認証を受けるようにしてください。 Azure CLI、Visual Studio Code、または Azure PowerShell を使って認証することができます。

Azure CLI で次のコマンドを使って Azure にサインインします。

az login

認証が完了したら、DefaultAzureCredential を使って、ストレージ アカウント内のキュー データにアクセスする QueueClient オブジェクトを作成および認可できます。 DefaultAzureCredential は、前の手順でサインインしたアカウントを自動的に検出して使用します。

DefaultAzureCredential を使用して承認するには、「パッケージをインストールする」の説明に従って、pom.xmlazure-identity 依存関係を追加していることを確認します。 また、App.java ファイルに com.azure.identity の import ディレクティブを追加してください。

import com.azure.identity.*;

キューの名前を決定し、承認に DefaultAzureCredential を使用して、QueueClient クラスのインスタンスを作成します。 このクライアント オブジェクトを使って、ストレージ アカウント内のキュー リソースを作成して操作します。

重要

キュー名に使用できるのは小文字、数字、ハイフンのみであり、名前の先頭は文字または数字にする必要があります。 各ハイフンの前後にはハイフン以外の文字を指定する必要があります。 また、名前は 3 から 63 文字で指定する必要があります。 キューの名前付けの詳細については、「キューとメタデータの名前付け」を参照してください。

main メソッド内に次のコードを追加し、<storage-account-name> プレースホルダー値を必ず置き換えてください。

System.out.println("Azure Queue Storage client library - Java quickstart sample\n");

// Create a unique name for the queue
String queueName = "quickstartqueues-" + java.util.UUID.randomUUID();

// Instantiate a QueueClient
// We'll use this client object to create and interact with the queue
// TODO: replace <storage-account-name> with the actual name
QueueClient queueClient = new QueueClientBuilder()
        .endpoint("https://<storage-account-name>.queue.core.windows.net/")
        .queueName(queueName)
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

Note

QueueClient クラスを使用して送信されるメッセージは、UTF-8 エンコードを使用して XML 要求に含めることができる形式である必要があります。 必要に応じて、QueueMessageEncoding オプションを BASE64 に設定して、準拠していないメッセージを処理できます。

キューを作成する

QueueClient オブジェクトを使い、create メソッドを呼び出してストレージ アカウントにキューを作成します。

main メソッドの末尾に次のコードを追加します。

System.out.println("Creating queue: " + queueName);

// Create the queue
queueClient.create();

メッセージをキューに追加する

以下のコード スニペットは、sendMessage メソッドを呼び出してキューにメッセージを追加します。 さらに、sendMessage の呼び出しから返された SendMessageResult を保存します。 この結果は、後でプログラムの中でメッセージを更新する際に使用します。

main メソッドの末尾に次のコードを追加します。

System.out.println("\nAdding messages to the queue...");

// Send several messages to the queue
queueClient.sendMessage("First message");
queueClient.sendMessage("Second message");

// Save the result so we can update this message later
SendMessageResult result = queueClient.sendMessage("Third message");

キュー内のメッセージを表示する

キュー内のメッセージをクイック表示するには、peekMessages メソッドを呼び出します。 このメソッドは、キューの先頭からメッセージを 1 つ以上取得しますが、メッセージの可視性は変更しません。

main メソッドの末尾に次のコードを追加します。

System.out.println("\nPeek at the messages in the queue...");

// Peek at messages in the queue
queueClient.peekMessages(10, null, null).forEach(
    peekedMessage -> System.out.println("Message: " + peekedMessage.getMessageText()));

キュー内のメッセージを更新する

メッセージの内容を更新するには、updateMessage メソッドを呼び出します。 メッセージの表示タイムアウトと内容は、このメソッドで変更できます。 メッセージの内容には UTF-8 でエンコードされた文字列を指定してください。最大サイズは 64 KB です。 先ほどこのコードの中で保存した SendMessageResult を使用して、メッセージ ID と PopReceipt を、新しいメッセージの内容と共に渡します。 更新するメッセージは、メッセージ ID と PopReceipt によって識別されます。

System.out.println("\nUpdating the third message in the queue...");

// Update a message using the result that
// was saved when sending the message
queueClient.updateMessage(result.getMessageId(),
                          result.getPopReceipt(),
                          "Third message has been updated",
                          Duration.ofSeconds(1));

キューの長さを取得する

キュー内のメッセージの概数を取得できます。

getProperties メソッドから、キューに現在置かれているメッセージの数など、いくつかの値が返されます。 要求の後でメッセージが追加または削除される可能性があるため、これらの値はあくまでも概数です。 getApproximateMessageCount メソッドからは、Queue Storage を呼び出さず、getProperties を呼び出すことで取得された最後の値が返されます。

QueueProperties properties = queueClient.getProperties();
long messageCount = properties.getApproximateMessagesCount();

System.out.println(String.format("Queue length: %d", messageCount));

キューからメッセージを受信して削除する

receiveMessages メソッドを呼び出して、先ほど追加したメッセージをダウンロードします。 このコード例では、メッセージを受信して処理した後、キューからメッセージを削除します。 ここでの処理は、単にメッセージをコンソールに表示するだけです。

ユーザーからの入力を待ってメッセージを受信、削除するために、System.console().readLine(); を呼び出してアプリを一時停止させます。 リソースが正しく作成されたことを Azure portal で確認してから、それらを削除してください。 明示的に削除されなかったメッセージは、最終的にキューに再表示され、別の機会に処理されます。

main メソッドの末尾に次のコードを追加します。

System.out.println("\nPress Enter key to receive messages and delete them from the queue...");
System.console().readLine();

// Get messages from the queue
queueClient.receiveMessages(10).forEach(
    // "Process" the message
    receivedMessage -> {
        System.out.println("Message: " + receivedMessage.getMessageText());

        // Let the service know we're finished with
        // the message and it can be safely deleted.
        queueClient.deleteMessage(receivedMessage.getMessageId(), receivedMessage.getPopReceipt());
    }
);

receiveMessages メソッドを呼び出す際、必要に応じて、maxMessages の値を指定できます。これは、キューから取得するメッセージの数です。 メッセージ数の既定値は 1、最大値は 32 です。 visibilityTimeout の値を指定することもできます。これにより、タイムアウト期間の他の操作からメッセージが非表示になります。 既定値は 30 秒です。

キューを削除する

次のコードでは、Delete メソッドを使用してキューを削除することにより、アプリによって作成されたリソースがクリーンアップされます。

main メソッドの末尾に次のコードを追加します。

System.out.println("\nPress Enter key to delete the queue...");
System.console().readLine();

// Clean up
System.out.println("Deleting queue: " + queueClient.getQueueName());
queueClient.delete();

System.out.println("Done");

コードの実行

このアプリは、3 つのメッセージを作成して Azure のキューに追加します。 コードでは、キュー内のメッセージを一覧表示した後にそれらを取得して削除してから、最後にキューを削除します。

コンソール ウィンドウで、お使いのアプリケーションのディレクトリに移動し、アプリケーションをビルドして実行します。

mvn compile

次に、パッケージをビルドします。

mvn package

次の mvn コマンドを使用して、アプリを実行します。

mvn exec:java -Dexec.mainClass="com.queues.quickstart.App" -Dexec.cleanupDaemonThreads=false

アプリの出力は、次の例のようになります。

Azure Queue Storage client library - Java quickstart sample

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Press Enter key to receive messages and delete them from the queue...

Message: First message
Message: Second message
Message: Third message has been updated

Press Enter key to delete the queue...

Deleting queue: quickstartqueues-fbf58f33-4d5a-41ac-ac0e-1a05d01c7003
Done

メッセージを受信する前にアプリが一時停止したら、Azure portal でストレージ アカウントを確認してください。 キューにメッセージが存在することを確認します。

Enter キーを押してメッセージを受信し、削除します。 確認を求められたら、もう一度 Enter キーを押してキューを削除し、デモを終了します。

次のステップ

このクイックスタートでは、Java コードを使用して、キューを作成し、そこにメッセージを追加する方法について説明しました。 その後、メッセージの表示、取得、削除について説明しました。 最後に、メッセージ キューを削除する方法を説明しました。

チュートリアル、サンプル、クイック スタートなどのドキュメントについては、次のページを参照してください。