Azure CosmosDB使用Java API添加附件技术咨询

我来帮你梳理下从Cloudant迁移到Cosmos DB后，用Java API创建PDF附件的具体步骤，刚好适合做小型POC验证：

一、准备环境：添加Cosmos DB Java SDK依赖 #

首先在你的Maven项目中添加最新的Cosmos DB SQL API SDK依赖（目前推荐4.x版本）：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-cosmos</artifactId>
    <version>4.56.0</version> <!-- 请用最新稳定版 -->
</dependency>

二、初始化Cosmos客户端 #

先建立和Cosmos DB的连接，把占位符替换成你的实际账户信息：

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.cosmos.CosmosContainer;
import com.azure.cosmos.CosmosDatabase;

public class CosmosAttachmentDemo {
    private static final String ENDPOINT = "你的Cosmos DB账户端点";
    private static final String KEY = "你的Cosmos DB账户密钥";
    private static final String DATABASE_NAME = "你的数据库名称";
    private static final String CONTAINER_NAME = "你的容器名称";

    public static void main(String[] args) {
        // 初始化客户端（try-with-resources自动关闭资源）
        try (CosmosClient cosmosClient = new CosmosClientBuilder()
                .endpoint(ENDPOINT)
                .key(KEY)
                .buildClient()) {
            CosmosDatabase database = cosmosClient.getDatabase(DATABASE_NAME);
            CosmosContainer container = database.getContainer(CONTAINER_NAME);
            
            // 调用创建附件的方法
            createPdfAttachment(container);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

三、方式1：直接将PDF嵌入Cosmos DB文档（适合小文件） #

Cosmos DB没有像Cloudant那样专门的Attachment API，但我们可以把PDF的二进制数据作为文档的一个字段存储（用Binary类型），完全满足POC需求：

import com.azure.cosmos.models.CosmosItemRequestOptions;
import com.azure.cosmos.models.CosmosItemResponse;
import com.azure.cosmos.models.PartitionKey;
import com.azure.cosmos.util.Binary;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;

private static void createPdfAttachment(CosmosContainer container) throws IOException {
    // 1. 读取本地PDF文件为字节数组
    byte[] pdfBytes = Files.readAllBytes(Paths.get("./test.pdf")); // 替换成你的PDF路径
    
    // 2. 构建包含附件信息的文档
    Map<String, Object> document = new HashMap<>();
    document.put("id", "pdf-doc-" + System.currentTimeMillis()); // 生成唯一文档ID
    document.put("fileName", "test.pdf");
    document.put("fileType", "application/pdf");
    document.put("fileContent", new Binary(pdfBytes)); // 用Binary类型存储二进制数据
    
    // 3. 插入文档到Cosmos DB（替换为你的分区键值）
    CosmosItemResponse<Map> response = container.createItem(
            document,
            new PartitionKey("user-001"), // 示例分区键值，根据你的容器配置修改
            new CosmosItemRequestOptions()
    );
    
    System.out.println("文档创建成功，状态码：" + response.getStatusCode());
}

验证方式：读取并还原PDF #

如果你想确认附件是否正确存储，可以写一段读取代码还原PDF：

private static void retrievePdfAttachment(CosmosContainer container, String docId, String partitionKey) throws IOException {
    CosmosItemResponse<Map> response = container.readItem(
            docId,
            new PartitionKey(partitionKey),
            Map.class
    );
    
    Map<String, Object> document = response.getItem();
    Binary binaryContent = (Binary) document.get("fileContent");
    byte[] pdfBytes = binaryContent.getBytes();
    
    // 将字节数组写入本地文件
    Files.write(Paths.get("./retrieved-test.pdf"), pdfBytes);
    System.out.println("PDF已成功还原到本地");
}

四、方式2：用Azure Blob Storage存储大PDF（最佳实践） #

如果你的PDF体积较大（超过2MB，Cosmos DB单文档默认上限），推荐用Azure Blob Storage存储文件，然后在Cosmos DB文档中保存Blob的访问链接和元数据，这也是Azure的官方最佳实践：

1. 添加Blob Storage SDK依赖 #

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>12.25.0</version> <!-- 最新稳定版 -->
</dependency>

2. 上传PDF到Blob并记录链接到Cosmos #

import com.azure.storage.blob.BlobClient;
import com.azure.storage.blob.BlobContainerClient;
import com.azure.storage.blob.BlobServiceClient;
import com.azure.storage.blob.BlobServiceClientBuilder;

private static void createPdfWithBlobLink(CosmosContainer container) throws IOException {
    // 初始化Blob客户端
    String blobConnectionString = "你的Blob Storage连接字符串";
    String blobContainerName = "pdf-storage"; // 替换为你的Blob容器名称
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .connectionString(blobConnectionString)
            .buildClient();
    BlobContainerClient blobContainerClient = blobServiceClient.getBlobContainerClient(blobContainerName);
    
    // 上传PDF到Blob
    String blobName = "test-" + System.currentTimeMillis() + ".pdf";
    BlobClient blobClient = blobContainerClient.getBlobClient(blobName);
    blobClient.uploadFromFile("./test.pdf"); // 替换为你的PDF路径
    
    // 构建Cosmos文档，存储Blob链接和元数据
    Map<String, Object> document = new HashMap<>();
    document.put("id", "doc-with-blob-" + System.currentTimeMillis());
    document.put("fileName", "test.pdf");
    document.put("fileType", "application/pdf");
    document.put("blobUrl", blobClient.getBlobUrl()); // 存储Blob的公共访问URL（需容器允许公共访问）
    
    // 插入文档到Cosmos
    CosmosItemResponse<Map> response = container.createItem(
            document,
            new PartitionKey("user-001"), // 替换为你的分区键值
            new CosmosItemRequestOptions()
    );
    
    System.out.println("带Blob链接的文档创建成功，状态码：" + response.getStatusCode());
}

注意事项 #

• 确保你的Cosmos DB容器已经提前创建，分区键选择要符合业务场景（比如用户ID、文档类型等）
• 生产环境中不要硬编码连接字符串和密钥，建议用Azure Key Vault统一管理
• 如果用方式1，注意单文档大小限制（默认2MB，可申请提升到10MB），超过上限必须用方式2

内容的提问来源于stack exchange，提问作者user680702