Quickstart: Azure Queue Storage client library for Java

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

API reference documentation | Library source code | Package (Maven) | Samples

Use the Azure Queue Storage client library for Java to:

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

前提条件

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

セットアップ

This section walks you through preparing a project to work with the Azure Queue Storage client library for Java.

プロジェクトを作成する

Create a Java application named queues-quickstart.

1. In a console window (such as cmd, PowerShell, or Bash), use Maven to create a new console app with the name queues-quickstart. Type the following mvn command to create a "Hello, world!" Java project.

   • 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. The output from generating the project should look something like this:

   [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
   

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

Open the pom.xml file in your text editor.

Add azure-sdk-bom to take a dependency on the latest version of the library. In the following snippet, replace the {bom_version_to_target} placeholder with the version number. Using azure-sdk-bom keeps you from having to specify the version of each individual dependency. To learn more about the BOM, see the Azure SDK BOM README.

<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>

Then add the following dependency elements to the group of dependencies. The azure-identity dependency is needed for passwordless connections to Azure services.

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

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

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

1. Navigate to the /src/main/java/com/queues/quickstart directory
2. Open the App.java file in your editor
3. Delete the System.out.println("Hello, world"); statement
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 日になります。

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

Use the following Java classes to interact with these resources:

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

コード例

These example code snippets show you how to do the following actions with the Azure Queue Storage client library for Java:

• アクセスの認可とクライアント オブジェクトの作成
• キューを作成する
• メッセージをキューに追加する
• キュー内のメッセージを表示する
• キュー内のメッセージを更新する
• キューの長さを取得する
• Receive and delete messages from a queue
• キューを削除する

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 メソッドを呼び出してストレージ アカウントにキューを作成します。

Add this code to the end of the main method:

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

// Create the queue
queueClient.create();

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

以下のコード スニペットは、sendMessage メソッドを呼び出してキューにメッセージを追加します。 It also saves a SendMessageResult returned from a sendMessage call. The result is used to update the message later in the program.

Add this code to the end of the main method:

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 つ以上取得しますが、メッセージの可視性は変更しません。

Add this code to the end of the main method:

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 です。 Along with new content for the message, pass in the message ID and pop receipt by using the SendMessageResult that was saved earlier in the code. The message ID and pop receipt identify which message to update.

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

キューの長さを取得する

キュー内のメッセージ数の見積もりを取得できます。

The getProperties method returns several values including the number of messages currently in a queue. The count is only approximate because messages can be added or removed after your request. The getApproximateMessageCount method returns the last value retrieved by the call to getProperties, without calling Queue Storage.

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

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

Receive and delete messages from a queue

Download previously added messages by calling the receiveMessages method. The example code also deletes messages from the queue after they're received and processed. ここでの処理は、単にメッセージをコンソールに表示するだけです。

The app pauses for user input by calling System.console().readLine(); before it receives and deletes the messages. リソースが正しく作成されたことを Azure portal で確認してから、それらを削除してください。 明示的に削除されなかったメッセージは、最終的にキューに再表示され、別の機会に処理されます。

Add this code to the end of the main method:

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 メソッドを使用してキューを削除することにより、アプリによって作成されたリソースがクリーンアップされます。

Add this code to the end of the main method:

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 のキューに追加します。 コードでは、キュー内のメッセージを一覧表示した後にそれらを取得して削除してから、最後にキューを削除します。

In your console window, navigate to your application directory, then build and run the application.

mvn compile

Then, build the package.

mvn package

Use the following mvn command to run the app.

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 キーを押してキューを削除し、デモを終了します。

次のステップ

In this quickstart, you learned how to create a queue and add messages to it using Java code. その後、メッセージの表示、取得、削除を学びました。 最後に、メッセージ キューを削除する方法を説明しました。

For tutorials, samples, quick starts, and other documentation, visit:

• For related code samples using deprecated Java version 8 SDKs, see Code samples using Java version 8.
• For more Azure Queue Storage sample apps, see Azure Queue Storage client library for Java - samples.