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

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

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

Java 用 Azure Queue Storage クライアント ライブラリを使用して、次の処理を行います。

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

前提条件

• Java Development Kit (JDK) バージョン 8 以降
• Apache Maven
• Azure サブスクリプション - 無料アカウントを作成する
• Azure Storage アカウント - ストレージ アカウントを作成する

セットアップ

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

プロジェクトを作成する

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

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

   • PowerShell
   • Bash

   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 はアカウント・キーよりも管理しやすく、セキュリティが優れており、パスワードレス認証が可能になります。 両方のオプションの例を次に示します。

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Queue Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Queue Data Contributor" `
    -Scope <yourStorageAccountId>

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

オブジェクト モデル

Azure Queue Storage は、大量のメッセージを格納するためのサービスです。 キュー メッセージのサイズは最大 64 KB です。 キューには、ストレージ アカウントの合計容量制限まで、数百万のメッセージが含まれる場合があります。 キューは、非同期的に処理する作業のバックログを作成するために一般的に使用されます。 Queue Storage には、次の 3 種類のリソースがあります。

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

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

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

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

コード例

次のコード スニペット例は、Java 用 Azure Queue Storage クライアント ライブラリで次のアクションを実行する方法を示しています。

• アクセスの認可とクライアント オブジェクトの作成
• キューを作成する
• メッセージをキューに追加する
• キュー内のメッセージを表示する
• キュー内のメッセージを更新する
• キューの長さを取得する
• キューからのメッセージの受信と削除
• キューを削除する

az login

az login

Connect-AzAccount

import com.azure.identity.*;

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

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

// Retrieve the connection string for use with the application. The storage
// connection string is stored in an environment variable on the machine
// running the application called AZURE_STORAGE_CONNECTION_STRING. If the environment variable
// is created after the application is launched in a console or with
// Visual Studio, the shell or application needs to be closed and reloaded
// to take the environment variable into account.
String connectStr = System.getenv("AZURE_STORAGE_CONNECTION_STRING");

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

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

// Instantiate a QueueClient
// We'll use this client object to create and interact with the queue
QueueClient queueClient = new QueueClientBuilder()
        .connectionString(connectStr)
        .queueName(queueName)
        .buildClient();

キューを作成する

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

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

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

// Create the queue
queueClient.create();

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

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

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 とポップ レシートを渡します。 メッセージ ID とポップ レシートは、更新するメッセージを識別します。

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 コードを使用してキューを作成し、キューにメッセージを追加する方法について説明しました。 その後、メッセージの表示、取得、削除を学びました。 最後に、メッセージ キューを削除する方法を説明しました。

チュートリアル、サンプル、クイック スタート、その他のドキュメントについては、以下を参照してください。

• 非推奨の Java バージョン 8 SDK を使用する関連コード サンプルについては、 Java バージョン 8 を使用したコード サンプルを参照してください。
• その他の Azure Queue Storage サンプル アプリについては、 Java 用の Azure Queue Storage クライアント ライブラリのサンプルに関するページを参照してください。