你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：适用于 Java 的 Azure 队列存储客户端库

2025-10-09

适用于 Java 的 Azure 队列存储客户端库入门。 Azure 队列存储是一项服务，用于存储大量消息以供以后检索和处理。请按照以下步骤安装包并试用基本任务的示例代码。

API 参考文档 | 库源代码 | 包（Maven） | 样品

使用适用于 Java 的 Azure 队列存储客户端库可以：

创建队列
将消息添加到队列
查看队列中的消息
更新队列中的消息
获取队列长度
从队列接收消息
从队列中删除消息
删除队列

先决条件

Java 开发工具包 (JDK) 8 或更高版本
Apache Maven
Azure 订阅 - 创建免费帐户
Azure 存储帐户 - 创建存储帐户

设置

本部分将指导你准备一个项目以使用适用于 Java 的 Azure 队列存储客户端库。

创建项目

创建名为 queues-quickstart 的 Java 应用程序。

在控制台窗口中（如 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

mvn archetype:generate \
    --define interactiveMode=n \
    --define groupId=com.queues.quickstart \
    --define artifactId=queues-quickstart \
    --define archetypeArtifactId=maven-archetype-quickstart \
    --define archetypeVersion=1.4

生成项目的输出应如下所示：

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

切换到新创建的 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>

然后将以下依赖项元素添加到依赖项组。与 Azure 服务建立无密码连接需要 azure 标识 依赖项。

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

设置应用框架

从项目目录中执行以下操作：

导航到 /src/main/java/com/queues/quickstart 目录
在编辑器中打开 App.java 文件
删除System.out.println("Hello, world");语句
添加 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 服务的应用程序请求必须获得授权。 DefaultAzureCredential建议使用 Azure 标识客户端库提供的类在代码中实现与 Azure 服务的无密码连接。

还可以使用密码、连接字符串或其他凭据直接授权对 Azure 服务的请求。但是，应谨慎使用此方法。开发人员必须勤奋地不要在不安全的位置公开这些机密。获得密码或密钥访问权限的任何人都可以进行身份验证。 DefaultAzureCredential 通过帐户密钥提供改进的管理和安全性优势，以允许无密码身份验证。以下示例演示了这两个选项。

无密码（推荐）
连接字符串

DefaultAzureCredential 是适用于 Java 的 Azure 标识客户端库提供的类。若要了解详细信息 DefaultAzureCredential，请参阅 DefaultAzureCredential 概述。 DefaultAzureCredential 支持多种身份验证方法，并确定应在运行时使用哪种方法。通过这种方法，你的应用可在不同环境（本地与生产）中使用不同的身份验证方法，而无需实现特定于环境的代码。

例如，应用可以在本地开发时使用 Azure CLI 登录凭据进行身份验证，在应用部署到 Azure 后则使用托管标识进行身份验证。此转换不需要更改代码。

在本地开发时，请确保访问队列数据的用户帐户具有正确的权限。需要具有“存储队列数据参与者”角色才能读取和写入队列数据。要为自己分配此角色，需要具有“用户访问管理员”角色或包含 Microsoft.Authorization/roleAssignments/write 操作的其他角色。可使用 Azure 门户、Azure CLI 或 Azure PowerShell 向用户分配 Azure RBAC 角色。可以在范围概述页上详细了解角色分配的可用范围。

在此方案中，你将向用户帐户分配权限（范围限定为存储帐户），以遵循最低特权原则。这种做法仅为用户提供所需的最低权限，并创建更安全的生产环境。

以下示例将 存储队列数据参与者 角色分配给用户帐户，该角色提供对存储帐户中队列数据的读取和写入访问权限。

重要

在大多数情况下，角色分配在 Azure 中传播需要一两分钟，最多可能需要 8 分钟，但这种情况极少见。如果在首次运行代码时收到身份验证错误，请稍等片刻再试。

Azure 门户
Azure CLI
PowerShell

在 Azure 门户中，使用主搜索栏或左侧导航找到存储帐户。
在存储帐户概述页上，从左侧菜单中选择 访问控制（IAM ）。
在“访问控制 (IAM)”页上，选择“角色分配”选项卡。
从顶部菜单中选择“+ 添加”，然后从出现的下拉菜单中选择“添加角色分配”。

显示如何分配角色的屏幕截图。

使用搜索框将结果筛选为所需角色。对于此示例，搜索 存储队列数据参与者 并选择匹配的结果，然后选择“ 下一步”。
在“访问权限分配对象”下，选择“用户、组或服务主体”，然后选择“+ 选择成员”。
在对话框中，搜索你的 Microsoft Entra 用户名（通常是你的 user@domain 电子邮件地址），然后在对话框的底部选择“选择”。
选择“查看 + 分配”转到最后一页，然后再次选择“查看 + 分配”来完成该过程。

若要使用 Azure CLI 在资源级别分配角色，必须先使用 az storage account show 命令检索资源 ID。可以使用 --query 参数筛选输出属性。

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

复制前一个命令的结果 Id。然后，可以使用 Azure CLI 的 az role 命令分配角色。

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

若要使用 Azure PowerShell 在资源级别分配角色，首先必须使用 Get-AzResource 命令检索资源 ID。

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

复制前面命令输出中的 Id 值。然后，可以使用 PowerShell 中的 New-AzRoleAssignment 命令分配角色。

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

从 Azure 门户复制凭据

当示例应用程序向 Azure 存储发出请求时，必须对其进行授权。若要授权请求，请将存储帐户凭据作为连接字符串添加到应用程序。若要查看存储帐户凭据，请执行以下步骤：

登录到 Azure 门户。
找到存储帐户。
在存储帐户菜单窗格中的“安全性 + 网络”下，选择“访问密钥”。在这里，可以查看帐户访问密钥和每个密钥的完整连接字符串。
在 “访问密钥 ”窗格中，选择“ 显示密钥”。
在 key1 部分中，找到 连接字符串 值。选择 “复制到剪贴板 ”图标以复制连接字符串。在下一部分中，将连接字符串值添加到环境变量。

配置存储连接字符串

复制连接字符串后，将其写入运行应用程序的本地计算机上的新环境变量。若要设置环境变量，请打开命令行窗口，并按照您操作系统的说明进行操作。将 <yourconnectionstring> 替换为实际的连接字符串。

Windows操作系统
Linux 和 macOS

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

在 Windows 中添加环境变量后，必须启动命令窗口的新实例。

重启程序

添加环境变量后，重启需要读取环境变量的任何正在运行的程序。例如，在继续之前，请重启开发环境或编辑器。

重要

应谨慎使用帐户访问密钥。如果帐户访问密钥丢失或意外放置在不安全的位置，服务可能会变得易受攻击。具有访问密钥的任何人都可以授权针对存储帐户的请求，并且实际上有权访问所有数据。 DefaultAzureCredential 提供了增强的安全特性和优势，是管理对 Azure 服务授权的推荐方案。

对象模型

Azure 队列存储是用于存储大量消息的服务。队列消息的大小最多可为 64 KB。队列可能包含数百万条消息，最大容量限制为存储帐户的总容量限制。队列通常用于创建以异步方式处理的积压工作。队列存储提供三种类型的资源：

存储帐户：对 Azure 存储的所有访问都通过存储帐户完成。有关存储帐户的详细信息，请参阅存储帐户概述
队列：队列包含一组消息。所有消息都必须位于队列中。请注意，队列名称必须全部为小写。有关命名队列的信息，请参阅命名队列和元数据。
消息：采用任意格式的消息，最大为 64 KB。消息最多可以保留在队列中 7 天。对于版本 2017-07-29 或更高版本，最长生存时间可以是任何正数，或 -1 指示消息未过期。如果省略此参数，则默认生存时间为 7 天。

下图显示了这些资源之间的关系。

队列存储体系结构示意图

使用以下 Java 类与这些资源进行交互：

QueueClientBuilder：类 QueueClientBuilder 配置并实例化对象 QueueClient 。
QueueServiceClient：QueueServiceClient 允许管理您存储帐户中的所有队列。
QueueClient：QueueClient 类允许您管理和操作单个队列及其消息。
QueueMessageItem：类 QueueMessageItem 表示在调用 ReceiveMessages 队列时返回的各个对象。

代码示例

这些示例代码片段演示如何使用适用于 Java 的 Azure 队列存储客户端库执行以下作：

授权访问并创建客户端对象
创建队列
将消息添加到队列
查看队列中的消息
更新队列中的消息
获取队列长度
从队列接收和删除消息
删除队列

无密码（推荐）
连接字符串

授权访问并创建客户端对象

请确保使用分配给该角色的同一Microsoft Entra 帐户进行身份验证。可以通过 Azure CLI、Visual Studio Code 或 Azure PowerShell 进行身份验证。

使用以下命令通过 Azure CLI 登录到 Azure：

az login

需要安装 Azure CLI 才能通过 Visual Studio 代码使用 DefaultAzureCredential 。

在 Visual Studio Code 的主菜单上，导航到“终端”>“新建终端”。

使用以下命令通过 Azure CLI 登录到 Azure：

az login

通过以下命令使用 PowerShell 登录到 Azure：

Connect-AzAccount

进行身份验证后，可以使用 QueueClient 创建和授权 DefaultAzureCredential 对象，以便访问存储帐户中的队列数据。 DefaultAzureCredential 自动发现并使用在上一步中登录的帐户。

若要授权使用DefaultAzureCredential，请确保已在中添加了pom.xml依赖项，如Install the packages中所述。此外，请确保在com.azure.identity文件中添加导入指令：

import com.azure.identity.*;

决定队列的名称，并使用QueueClient进行授权，然后创建DefaultAzureCredential类的实例。我们使用此客户端对象创建和与存储帐户中的队列资源交互。

重要

队列名称只能包含小写字母、数字和连字符，并且必须以字母或数字开头。每个连字符的前后必须为非连字符字符。该名称的长度必须介于 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();

获取连接字符串并创建客户端

以下代码检索存储帐户的连接字符串。连接字符串存储在“ 配置存储连接字符串 ”部分中创建的环境变量中。

在方法中添加 main 以下代码：

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

确定队列的名称并创建 QueueClient 类的实例，使用连接字符串进行授权。我们使用此客户端对象创建和与存储帐户中的队列资源交互。

重要

队列名称只能包含小写字母、数字和连字符，并且必须以字母或数字开头。每个连字符的前后必须为非连字符字符。该名称的长度必须介于 3 到 63 个字符之间。有关详细信息，请参阅命名队列和元数据。

将此代码添加到方法的 main 末尾：

// 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 类发送的消息必须采用可以包含在采用 UTF-8 编码的 XML 请求中的格式。可以选择将 QueueMessageEncoding 选项设置为 BASE64 来处理不符合标准的消息。

创建队列

使用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 该方法查看队列中的消息。此方法从队列前面检索一个或多个消息，但不会更改消息的可见性。

将此代码添加到方法的 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 方法更新消息的内容。此方法可以更改消息的可见性超时和内容。消息内容必须是最大大小为 64 KB 的 UTF-8 编码字符串。除了该消息的新内容，还会使用 SendMessageResult 传入代码中之前保存的消息 ID 和 POP 收据。消息 ID 和 POP 收据标识要更新的消息。

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 返回调用 getProperties所检索的最后一个值，而不调用队列存储。

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

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

从队列接收和删除消息

通过调用 receiveMessages 该方法下载以前添加的消息。示例代码还会在收到和处理消息后从队列中删除消息。在这种情况下，处理只是在控制台上显示消息。

应用在接收和删除消息之前通过调用 System.console().readLine(); 暂停用户输入。在 Azure 门户中验证资源是否已正确创建，然后再将其删除。未显式删除的任何消息会最终在队列中重新出现，以便再次进行处理。

将此代码添加到方法的 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");

运行代码

此应用创建并向 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 门户中检查存储帐户。验证消息是否在队列中。

Enter按键接收和删除消息。出现提示时，再次按 Enter 该键以删除队列并完成演示。

后续步骤

在本快速入门中，你学习了如何使用 Java 代码创建队列并向其添加消息。然后，你已了解如何查看、检索和删除消息。最后，你了解了如何删除消息队列。

有关教程、示例、快速入门和其他文档，请访问：

面向 Java 云开发人员的 Azure

有关使用已弃用的 Java 版本 8 SDK 的相关代码示例，请参阅使用 Java 版本 8 的代码示例。
有关更多 Azure 队列存储示例应用，请参阅适用于 Java 的 Azure 队列存储客户端库 - 示例。

反馈

此页面是否有帮助？

通过

快速入门：适用于 Java 的 Azure 队列存储客户端库

先决条件

设置

创建项目

安装软件包

设置应用框架

向 Azure 进行身份验证

对象模型

代码示例

授权访问并创建客户端对象

创建队列

将消息添加到队列

查看队列中的消息

更新队列中的消息

获取队列长度

从队列接收和删除消息

删除队列

运行代码

后续步骤

反馈

其他资源