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

适用于 Java 的 Azure 密钥保管库 机密客户端库 - 版本 4.7.1

Azure 密钥保管库 是一种云服务，可为密码和数据库连接字符串等机密提供安全存储。

使用 Azure 密钥保管库机密客户端库，可以安全地存储和严格控制对令牌、密码、API 密钥和其他机密的访问。 此库提供创建、检索、更新、删除、清除、备份、还原和列出机密及其版本的操作。

使用 Azure 密钥保管库机密客户端库创建和管理机密。

源代码 | API 参考文档 | 产品文档 | 示例

入门

添加包

包括 BOM 文件

请将 包含在 azure-sdk-bom 项目中，以依赖于库的正式发布 (正式发布) 版本。 在以下代码段中，将 {bom_version_to_target} 占位符替换为版本号。 若要详细了解 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>

然后在 dependencies 节中包含直接依赖项，不带版本标记，如下所示。

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-security-keyvault-secrets</artifactId>
    </dependency>
</dependencies>

包括直接依赖项

如果要依赖于 BOM 中不存在的特定版本的库，请将直接依赖项添加到项目中，如下所示。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-security-keyvault-secrets</artifactId>
    <version>4.7.1</version>
</dependency>

先决条件

• Java 开发工具包 (JDK) 8 或更高版本。
• 一个 Azure 订阅。
• 现有的 Azure 密钥保管库。 如果需要创建密钥保管库，可以在 Azure 门户中按照 本文档中的步骤操作。 或者，可以按照 本文档中的步骤使用 Azure CLI。

验证客户端

若要与 Azure 密钥保管库 服务交互，需要创建 类的SecretClient实例、保管库 URL 和凭据对象。 本文档中显示的示例使用名为 的 DefaultAzureCredential凭据对象，该对象适用于大多数方案，包括本地开发和生产环境。 此外，我们建议使用 托管标识 在生产环境中进行身份验证。

可以在 Azure 标识文档中找到有关不同身份验证方式及其相应凭据类型的详细信息。

创建机密客户端

执行 最适合你的身份验证设置 并将 your-key-vault-url 替换为密钥保管库的 URL 后，可以创建 SecretClient：

SecretClient secretClient = new SecretClientBuilder()
    .vaultUrl("<your-key-vault-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

注意：对于使用异步客户端，请使用 SecretAsyncClient 而不是 SecretClient 和 调用 buildAsyncClient()。

关键概念

机密

机密是 Azure 密钥保管库中的基本资源。 从开发人员的角度来看，Key Vault API 接受机密值并将其作为字符串返回。 除机密数据外，还可以指定以下属性：

• enabled：指定是否可以检索机密数据。
• notBefore：标识机密将处于活动状态的时间。
• expires：标识不应检索机密数据的过期时间。
• created：指示创建此版本的机密。
• updated：指示更新此版本的机密的时间。

机密客户端：

机密客户端与 Azure 密钥保管库 服务执行交互，以获取、设置、更新、删除和列出机密及其版本。 异步 (SecretAsyncClient) 和同步 (SecretClient) 客户端存在于 SDK 中，允许根据应用程序的用例选择客户端。 初始化机密后，可以与密钥保管库中的主要资源类型进行交互。

示例

同步 API

以下部分提供了几个代码片段，涵盖了一些最常见的 Azure 密钥保管库机密服务任务，包括：

• 创建机密
• 检索机密
• 更新现有机密
• 删除机密
• 列出机密

创建机密

创建要存储在 Azure 密钥保管库中的机密。

• setSecret在 Azure 密钥保管库中创建新机密。 如果已存在具有给定名称的机密，则会创建该机密的新版本。

KeyVaultSecret secret = secretClient.setSecret("<secret-name>", "<secret-value>");
System.out.printf("Secret created with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue());

检索机密

通过调用 getSecret检索以前存储的机密。

KeyVaultSecret secret = secretClient.getSecret("<secret-name>");
System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue());

更新现有机密

通过调用 updateSecretProperties更新现有机密。

// Get the secret to update.
KeyVaultSecret secret = secretClient.getSecret("<secret-name>");
// Update the expiry time of the secret.
secret.getProperties().setExpiresOn(OffsetDateTime.now().plusDays(30));
SecretProperties updatedSecretProperties = secretClient.updateSecretProperties(secret.getProperties());
System.out.printf("Secret's updated expiry time: %s%n", updatedSecretProperties.getExpiresOn());

删除机密

通过调用 beginDeleteSecret删除现有机密。

SyncPoller<DeletedSecret, Void> deletedSecretPoller = secretClient.beginDeleteSecret("<secret-name>");

// Deleted secret is accessible as soon as polling begins.
PollResponse<DeletedSecret> deletedSecretPollResponse = deletedSecretPoller.poll();

// Deletion date only works for a SoftDelete-enabled Key Vault.
System.out.printf("Deletion date: %s%n", deletedSecretPollResponse.getValue().getDeletedOn());

// Secret is being deleted on server.
deletedSecretPoller.waitForCompletion();

列出机密

通过调用 listPropertiesOfSecrets列出 Azure 密钥保管库中的机密。

// List operations don't return the secrets with value information. So, for each returned secret we call getSecret to
// get the secret with its value information.
for (SecretProperties secretProperties : secretClient.listPropertiesOfSecrets()) {
    KeyVaultSecret secretWithValue = secretClient.getSecret(secretProperties.getName(), secretProperties.getVersion());
    System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secretWithValue.getName(),
        secretWithValue.getValue());
}

异步 API

以下部分提供了几个代码片段，涵盖了一些最常见的异步 Azure 密钥保管库特勤任务，包括：

• 异步创建机密
• 异步检索机密
• 异步更新现有机密
• 异步删除机密
• 异步列出机密

注意：应在main类/线程中的函数调用后添加 System.in.read() 或 Thread.sleep() ，以允许在main应用程序/线程退出之前执行和完成异步函数/操作。

异步创建机密

创建要存储在 Azure 密钥保管库中的机密。

• setSecret在 Azure 密钥保管库中创建新机密。 如果已存在具有给定名称的机密，则会创建该机密的新版本。

secretAsyncClient.setSecret("<secret-name>", "<secret-value>")
    .subscribe(secret -> System.out.printf("Created secret with name \"%s\" and value \"%s\"%n",
        secret.getName(), secret.getValue()));

异步检索机密

通过调用 getSecret检索以前存储的机密。

secretAsyncClient.getSecret("<secret-name>")
    .subscribe(secret -> System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n",
        secret.getName(), secret.getValue()));

异步更新现有机密

通过调用 updateSecretProperties更新现有机密。

secretAsyncClient.getSecret("<secret-name>")
    .flatMap(secret -> {
        // Update the expiry time of the secret.
        secret.getProperties().setExpiresOn(OffsetDateTime.now().plusDays(50));
        return secretAsyncClient.updateSecretProperties(secret.getProperties());
    }).subscribe(updatedSecretProperties ->
        System.out.printf("Secret's updated expiry time: %s%n", updatedSecretProperties.getExpiresOn()));

异步删除机密

通过调用 beginDeleteSecret删除现有机密。

secretAsyncClient.beginDeleteSecret("<secret-name>")
    .subscribe(pollResponse -> {
        System.out.printf("Deletion status: %s%n", pollResponse.getStatus());
        System.out.printf("Deleted secret name: %s%n", pollResponse.getValue().getName());
        System.out.printf("Deleted secret value: %s%n", pollResponse.getValue().getValue());
    });

异步列出机密

通过调用 listPropertiesOfSecrets列出 Azure 密钥保管库中的机密。

// The List secrets operation returns secrets without their value, so for each secret returned we call `getSecret`
// to get its value as well.
secretAsyncClient.listPropertiesOfSecrets()
    .flatMap(secretProperties ->
        secretAsyncClient.getSecret(secretProperties.getName(), secretProperties.getVersion()))
    .subscribe(secretResponse ->
        System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secretResponse.getName(),
            secretResponse.getValue()));

疑难解答

有关如何诊断各种故障方案的详细信息，请参阅 故障排除指南 。

常规

Azure 密钥保管库机密客户端会引发异常。 例如，如果在删除机密后尝试检索机密，则会返回错误 404 ，指示找不到资源。 以下代码片段通过捕获异常并显示有关错误的其他信息来妥善处理该错误。

try {
    secretClient.getSecret("<deleted-secret-name>");
} catch (ResourceNotFoundException e) {
    System.out.println(e.getMessage());
}

默认的 HTTP 客户端

默认情况下，所有客户端库都使用 Netty HTTP 客户端。 添加上述依赖项会自动将客户端库配置为使用 Netty HTTP 客户端。 HTTP 客户端 Wiki 中详述了如何配置或更改 HTTP 客户端。

默认 SSL 库

默认情况下，所有客户端库均使用 Tomcat 原生 Boring SSL 库来为 SSL 操作启用原生级别性能。 无聊 SSL 库是一个 Uber JAR，包含适用于 Linux/macOS/Windows 的本机库，与 JDK 中的默认 SSL 实现相比，性能更佳。 有关详细信息（包括如何减小依赖项大小），请参阅 Wiki 的性能优化部分。

后续步骤

SDK 的 GitHub 存储库中提供了多个密钥保管库 Java SDK 示例。 这些示例为使用 Azure 密钥保管库 时经常遇到的其他方案提供了示例代码。

后续步骤示例

此处详细介绍了示例。

其他文档

有关 Azure 密钥保管库的更多文档，请参阅 API 参考文档。

贡献

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 https://cla.microsoft.com 。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答；若有其他任何问题或意见，请联系 opencode@microsoft.com。