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

适用于 Java 的 Azure Cosmos DB 客户端库 - 版本 4.52.0

项目
10/25/2023

Azure Cosmos DB 是 Microsoft 针对操作和分析工作负荷提供的全球分布式多模型数据库服务。它通过自动缩放吞吐量、计算和存储来提供多主数据库功能。此项目提供 Java 中的 SDK 库，用于与 Azure Cosmos DB 数据库服务的 SQL API 进行交互。

源代码 | 包 (Maven) | API 参考文档 | 产品文档 | 样品

入门

添加包

包括 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-cosmos</artifactId>
  </dependency>
</dependencies>

包括直接依赖项

如果要依赖于 BOM 中不存在的特定库版本，请将直接依赖项添加到项目，如下所示。 //： # ({x-version-update-start;com.azure：azure-cosmos;current})

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-cosmos</artifactId>
  <version>4.52.0</version>
</dependency>

有关以前的版本，请参阅 maven central

有关包的更多详细信息，请参阅 javadocs

先决条件

Java 开发工具包 (JDK) 版本 8 或更高版本
有效的 Azure 帐户。如果没有，可以注册免费帐户。另外，可使用 Azure Cosmos DB 仿真器进行开发和测试。由于模拟器 https 证书是自签名的，因此需要将其证书导入 Java 受信任的证书存储，如此处所述
（可选）SLF4J 是一种日志外观。
（可选）SLF4J 绑定用于将特定的记录框架与 SLF4J 相关联。
（可选）Maven

仅当计划使用日志记录时，才需要 SLF4J。还请下载 SLF4J 绑定，该绑定可将 SLF4J API 与你选择的记录实现链接在一起。有关详细信息，请参阅 SLF4J 用户手册。

SDK 提供基于 Reactor Core 的异步 API。可在此处阅读有关 Reactor Core 和 Flux/Mono 类型的详细信息

验证客户端

若要与 Azure Cosmos DB 服务交互，需要创建 Cosmos Client 类的实例。为此，需要 Azure Cosmos DB 服务的 URL 和密钥。

SDK 提供两个客户端。

CosmosAsyncClient 使用异步 API 的操作。
CosmosClient 用于使用同步 (阻止) API 的操作。

创建 CosmosAsyncClient

CosmosAsyncClient cosmosAsyncClient = new CosmosClientBuilder()
    .endpoint(serviceEndpoint)
    .key(key)
    .buildAsyncClient();

创建 CosmosClient

CosmosClient cosmosClient = new CosmosClientBuilder()
    .endpoint(serviceEndpoint)
    .key(key)
    .buildClient();

关键概念

Azure Cosmos DB Java SDK 提供客户端逻辑表示形式来访问 Azure Cosmos DB SQL API。 Cosmos DB 帐户包含零个或多个数据库，数据库 (DB) 包含零个或多个容器，容器包含零个或多个项。可在此处阅读有关数据库、容器和项的详细信息。在容器级别定义的一些重要属性包括预配吞吐量和分区键。

全局分发

Azure Cosmos DB 是一个全局分布式数据库服务，旨在提供低延迟、吞吐量弹性缩放和明确定义的语义，以实现数据一致性和高可用性。简言之，如果应用程序需要在世界任何地方保证的快速响应时间，如果需要始终联机，并且需要无限和弹性的吞吐量和存储可伸缩性，则应在 Azure Cosmos DB 上构建应用程序。可在此处阅读有关全球分发的详细信息。

吞吐量预配

Azure Cosmos DB 允许对数据库和容器设置预配吞吐量。有两种类型的预配吞吐量：标准（手动）或自动缩放。可以按单容器粒度或单数据库粒度选择预配吞吐量，但通常首选容器级别吞吐量规范。可在此处阅读有关吞吐量预配的详细信息。

请求单位 (RU)

Azure Cosmos DB 支持多种 API，例如 SQL、MongoDB、Cassandra、Gremlin 和表。每个 API 具有自身的数据库操作集。这些操作包括简单的点读取和写入，以及复杂的查询等等。每个数据库操作根据其复杂性消耗系统资源。所有数据库操作的成本将由 Azure Cosmos DB 规范化，并以“请求单位”（简称 RU）表示。可将每秒 RU 数视为吞吐量的货币。每秒 RU 数是基于费率的货币。它抽象化了执行 Azure Cosmos DB 支持的数据库操作所需的系统资源，例如 CPU、IOPS 和内存。可在此处阅读有关请求单位的详细信息。

分区

将项插入 Cosmos DB 容器时，数据库会添加更多的存储和计算来处理请求，以水平方式增长。存储和计算容量添加到称为分区的离散单元中，你必须在文档中选择一个字段作为分区键，以便将每个文档映射到分区。分区的管理方式是从分区键值的范围内为每个分区分配一个大致相等的切片；因此，建议选择相对随机或均匀分布的分区键。否则，某些分区看到的请求数会多得多（热分区），而其他分区看到的请求数会少得多（冷分区），这是应该避免的。可以在此处详细了解分区。

示例

以下部分提供了几个代码片段，涵盖一些最常见的 Cosmos DB SQL API 任务，包括：

创建 Cosmos 客户端
创建数据库
创建容器
对项执行 CRUD 操作

创建 Cosmos 客户端

// Create a new CosmosAsyncClient via the CosmosClientBuilder
// It only requires endpoint and key, but other useful settings are available
CosmosAsyncClient cosmosAsyncClient = new CosmosClientBuilder()
    .endpoint("<YOUR ENDPOINT HERE>")
    .key("<YOUR KEY HERE>")
    .buildAsyncClient();

// Create a new CosmosClient via the CosmosClientBuilder
CosmosClient cosmosClient = new CosmosClientBuilder()
    .endpoint("<YOUR ENDPOINT HERE>")
    .key("<YOUR KEY HERE>")
    .buildClient();

// Create a new CosmosClient with customizations
cosmosClient = new CosmosClientBuilder()
    .endpoint(serviceEndpoint)
    .key(key)
    .directMode(directConnectionConfig, gatewayConnectionConfig)
    .consistencyLevel(ConsistencyLevel.SESSION)
    .connectionSharingAcrossClientsEnabled(true)
    .contentResponseOnWriteEnabled(true)
    .userAgentSuffix("my-application1-client")
    .preferredRegions(Arrays.asList("West US", "East US"))
    .buildClient();

创建数据库

使用在上一示例中创建的任何一个客户端，可以创建如下所示的数据库：

// Get a reference to the container
// This will create (or read) a database and its container.
cosmosAsyncClient.createDatabaseIfNotExists("<YOUR DATABASE NAME>")
    // TIP: Our APIs are Reactor Core based, so try to chain your calls
    .map(databaseResponse -> cosmosAsyncClient.getDatabase(databaseResponse.getProperties().getId()))
    .subscribe(database -> System.out.printf("Created database '%s'.%n", database.getId()));

创建容器

使用上述创建的数据库，可以将另一个操作链接到该数据库，以创建容器，如下所示：

cosmosAsyncClient.createDatabaseIfNotExists("<YOUR DATABASE NAME>")
    // TIP: Our APIs are Reactor Core based, so try to chain your calls
    .flatMap(databaseResponse -> {
        String databaseId = databaseResponse.getProperties().getId();
        return cosmosAsyncClient.getDatabase(databaseId)
            // Create Container
            .createContainerIfNotExists("<YOUR CONTAINER NAME>", "/id")
            .map(containerResponse -> cosmosAsyncClient.getDatabase(databaseId)
                .getContainer(containerResponse.getProperties().getId()));
    })
    .subscribe(container -> System.out.printf("Created container '%s' in database '%s'.%n",
        container.getId(), container.getDatabase().getId()));

对项执行 CRUD 操作

// Create an item
cosmosAsyncContainer.createItem(new Passenger("carla.davis@outlook.com", "Carla Davis", "SEA", "IND"))
    .flatMap(response -> {
        System.out.println("Created item: " + response.getItem());
        // Read that item 👓
        return cosmosAsyncContainer.readItem(response.getItem().getId(),
            new PartitionKey(response.getItem().getId()), Passenger.class);
    })
    .flatMap(response -> {
        System.out.println("Read item: " + response.getItem());
        // Replace that item 🔁
        Passenger p = response.getItem();
        p.setDestination("SFO");
        return cosmosAsyncContainer.replaceItem(p, response.getItem().getId(),
            new PartitionKey(response.getItem().getId()));
    })
    // delete that item 💣
    .flatMap(response -> cosmosAsyncContainer.deleteItem(response.getItem().getId(),
        new PartitionKey(response.getItem().getId())))
    .block(); // Blocking for demo purposes (avoid doing this in production unless you must)
// ...

此处提供了入门示例应用。

此外，我们还提供了更多示例项目示例。

疑难解答

常规

Azure Cosmos DB 是一个快速、弹性的分布式数据库，可以在提供延迟与吞吐量保证的情况下无缝缩放。凭借 Azure Cosmos DB，无需对体系结构进行重大更改或编写复杂的代码即可缩放数据库。扩展和缩减操作就像执行单个 API 调用或 SDK 方法调用一样简单。但是，由于 Azure Cosmos DB 是通过网络调用访问的，因此，使用 Azure Cosmos DB Java SDK v4 时，可以通过客户端优化获得最高性能。

性能指南介绍了这些客户端优化。
故障排除指南介绍了将 Azure Cosmos DB Java SDK v4 与 Azure Cosmos DB SQL API 帐户配合使用时的常见问题、解决方法、诊断步骤和工具。

启用客户端日志记录

Azure Cosmos DB Java SDK v4 使用 SLF4j 作为日志外观，支持记录到常用的日志框架，如 log4j 和 logback。

例如，如果要使用 log4j 作为日志记录框架，请在 Java classpath 中添加以下库。

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-log4j12</artifactId>
  <version>${slf4j.version}</version>
</dependency>
<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>${log4j.version}</version>
</dependency>

同时添加 log4j 配置。

# this is a sample log4j configuration

# Set root logger level to INFO and its only appender to A1.
log4j.rootLogger=INFO, A1

log4j.category.com.azure.cosmos=INFO
#log4j.category.io.netty=OFF
#log4j.category.io.projectreactor=OFF
# A1 is set to be a ConsoleAppender.
log4j.appender.A1=org.apache.log4j.ConsoleAppender

# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d %5X{pid} [%t] %-5p %c - %m%n

后续步骤

此处详细介绍了示例
完成快速入门 - 生成 Java 应用来管理 Cosmos DB SQL API 数据
阅读有关 Azure Cosmos DB 服务的详细信息

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。

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

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

曝光数

通过