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

适用于 Java 的 Azure 存储 Blob 加密客户端库 - 版本 12.23.1

Azure Blob 存储是 Microsoft 提供的适用于云的对象存储解决方案。 Blob 存储最适合存储巨量的非结构化数据。 非结构化数据是不遵循特定数据模型或定义（如文本或二进制数据）的数据。 此包支持 Blob 存储的客户端加密。

源代码 | API 参考文档 | REST API 文档 | 产品文档 | 样品

入门

先决条件

• Java 开发工具包 (版本 8 或更高版本的 JDK)
• Azure 订阅
• 创建存储帐户

添加包

包括 BOM 文件

请将 azure-sdk-bom 包含在项目中，以依赖于库的 GA 版本。 在以下代码段中，将 {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>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob-cryptography</artifactId>
  </dependency>
</dependencies>

包括直接依赖项

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

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-blob-cryptography</artifactId>
  <version>12.23.1</version>
</dependency>

创建存储帐户

若要创建存储帐户，可以使用 Azure 门户 或 Azure CLI。

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

验证客户端

若要与存储服务 (Blob、队列、消息、MessageId、File) 需要创建服务客户端类的实例。 为此，需要帐户 SAS (共享访问签名) 存储帐户字符串。 有关详细信息，请参阅 SAS 令牌

获取凭据

• SAS 令牌

a. 使用以下 Azure CLI 代码片段从存储帐户获取 SAS 令牌。

az storage blob generate-sas \
    --account-name {Storage Account name} \
    --container-name {container name} \
    --name {blob name} \
    --permissions {permissions to grant} \
    --expiry {datetime to expire the SAS token} \
    --services {storage services the SAS allows} \
    --resource-types {resource types the SAS allows}

例如：

CONNECTION_STRING=<connection-string>

az storage blob generate-sas \
    --account-name MyStorageAccount \
    --container-name MyContainer \
    --name MyBlob \
    --permissions racdw \
    --expiry 2020-06-15

b. 或者，从 Azure 门户获取帐户 SAS 令牌。

1. 转到存储帐户
2. Shared access signature从左侧菜单中选择
3. 在设置) 后单击 Generate SAS and connection string “ (”

共享密钥凭据

a. 使用“帐户名称”和“帐户密钥”。 帐户名称是存储帐户名称。

1. 转到存储帐户
2. Access keys从左侧菜单中选择
3. 在下key1/key2复制字段的内容Key

或

b. 使用连接字符串。

1. 转到存储帐户
2. Access keys从左侧菜单中选择
3. 在下key1/key2复制字段的内容Connection string

关键概念

Blob 存储用于：

• 直接向浏览器提供图像或文档。
• 存储文件以供分布式访问。
• 对视频和音频进行流式处理。
• 向日志文件进行写入。
• 存储用于备份和还原、灾难恢复及存档的数据。
• 存储数据以供本地或 Azure 托管服务执行分析。

示例

注意： 的用法与等效BlobClient的 EncryptedBlobClient 用法相同，唯一的区别在于客户端构造。 有关的常见用例，请参阅azure-storage-blobBlobClient

以下部分提供了几个代码片段，涵盖了一些最常见的 Azure 存储 Blob 加密创建任务，包括：

• EncryptedBlobClient从 创建BlobClient
• 创建 EncryptedBlobClient
• 使用 LocalKeyEncryptionKey
• 使用 KeyVaultKey

EncryptedBlobClient从 创建BlobClient

EncryptedBlobClient使用 BlobClient创建 。 BlobClient 自述文件中 azure-storage-blob 介绍了构造。

EncryptedBlobClient client = new EncryptedBlobClientBuilder()
    .key(key, keyWrapAlgorithm)
    .keyResolver(keyResolver)
    .blobClient(blobClient)
    .buildEncryptedBlobClient();

创建 EncryptedBlobClient

BlobServiceClient使用连接字符串创建 。

EncryptedBlobClient client = new EncryptedBlobClientBuilder()
    .key(key, keyWrapAlgorithm)
    .keyResolver(keyResolver)
    .connectionString(connectionString)
    .containerName(containerName)
    .blobName(blobName)
    .buildEncryptedBlobClient();

使用本地 KeyEncryptionKey

JsonWebKey localKey = JsonWebKey.fromAes(new SecretKeySpec(keyBytes, secretKeyAlgorithm),
    Arrays.asList(KeyOperation.WRAP_KEY, KeyOperation.UNWRAP_KEY))
    .setId("my-id");
AsyncKeyEncryptionKey akek = new KeyEncryptionKeyClientBuilder()
    .buildAsyncKeyEncryptionKey(localKey).block();

EncryptedBlobClient client = new EncryptedBlobClientBuilder()
    .key(akek, keyWrapAlgorithm)
    .connectionString(connectionString)
    .containerName(containerName)
    .blobName(blobName)
    .buildEncryptedBlobClient();

使用 KeyVaultKey

KeyClient keyClient = new KeyClientBuilder()
    .vaultUrl(keyVaultUrl)
    .credential(tokenCredential)
    .buildClient();
KeyVaultKey rsaKey = keyClient.createRsaKey(new CreateRsaKeyOptions(keyName)
    .setExpiresOn(OffsetDateTime.now().plusYears(1))
    .setKeySize(2048));
AsyncKeyEncryptionKey akek = new KeyEncryptionKeyClientBuilder()
    .credential(tokenCredential)
    .buildAsyncKeyEncryptionKey(rsaKey.getId())
    .block();

EncryptedBlobClient client = new EncryptedBlobClientBuilder()
    .key(akek, keyWrapAlgorithm)
    .connectionString(connectionString)
    .containerName(containerName)
    .blobName(blobName)
    .buildEncryptedBlobClient();

疑难解答

使用此 Java 客户端库与 Blob 交互时，服务返回的错误对应于为 REST API 请求返回的相同 HTTP 状态代码。 例如，如果尝试检索存储帐户中不存在的容器或 Blob，则会返回错误 404 ，指示 Not Found。

默认的 HTTP 客户端

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

默认 SSL 库

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

后续步骤

贡献

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

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

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