使用 Azure Cosmos DB NoSQL API 访问数据

项目
01/23/2025

本文介绍如何将 Spring Cloud Azure Starter for Spring Data for Azure Cosmos DB 添加到自定义应用程序。通过这个入门工具，你可以使用 Spring Data 和 Azure Cosmos DB for NoSQL 来在 Azure Cosmos DB 数据库中存储和检索数据。本文首先介绍如何通过 Azure 门户创建 Azure Cosmos DB。然后，本文介绍如何使用 Spring Initializr 创建自定义 Spring Boot 应用程序，该应用程序可与 Spring Boot Starter 配合使用。

Azure Cosmos DB 是一种全球分布式数据库服务，开发人员可以使用各种标准 API（例如 SQL、MongoDB、Graph 和表 API）处理数据。 Microsoft的 Spring Boot Starter 使开发人员能够使用与 Azure Cosmos DB for NoSQL 轻松集成的 Spring Boot 应用程序。

先决条件

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

使用 Azure 门户创建 Azure Cosmos DB

使用以下步骤创建 Azure Cosmos DB 实例：

浏览到 Azure 门户，然后选择创建资源。
选择 数据库，然后选择 Azure Cosmos DB。
在创建 Azure Cosmos DB 帐户屏幕上，选择 Azure Cosmos DB for NoSQL。
在 Azure Cosmos DB 页上，输入以下信息：
- 选择想用于数据库的订阅。
- 指定是为数据库创建新的 资源组，还是选择现有的资源组。
- 输入一个唯一的 帐户名称，该名称将用作您的数据库的 URI。例如：contosoaccounttest。
- 为数据库指定位置。
- 如果想创建一个仅用于演示目的的帐户，请选择应用免费层折扣。
- 保留默认选项和设置的其余部分。
选择查看 + 创建，查看你的规范，然后选择创建。
创建数据库后，该数据库将列在 Azure 仪表板，并在所有资源和 Azure Cosmos DB 页上列出。若要为新创建的 Azure Cosmos DB 创建数据库和容器，请参阅添加数据库和容器部分快速入门：从 Azure 门户创建 Azure Cosmos DB 帐户、数据库、容器和项。可以为其中任一位置选择数据库，以打开缓存的属性页。
显示数据库的属性页时，请选择密钥并复制数据库的 URI 和访问密钥。在 Spring Boot 应用程序中使用这些值。

重要

在新创建的 Azure Cosmos DB 中，将 Owner 角色分配给当前使用的 Azure 帐户。有关详细信息，请参阅使用 Azure 门户分配 Azure 角色。

使用 Spring Initializr 创建 Spring Boot 应用程序

使用以下步骤通过 Azure 支持创建新的 Spring Boot 应用程序项目。或者，可以在 azure-spring-boot-samples 存储库中使用 spring-cloud-azure-data-cosmos-sample 示例。然后，可以直接跳到生成和测试你的应用。

浏览到 https://start.spring.io/。
指定以下选项：
- 使用 Java生成 Maven 项目。
- 将 Spring Boot 版本指定为 2.7.11。
- 指定应用程序的“组”和“项目”名称。
- 为 Java 版本选择 17。
- 在依赖项中添加 Azure 支持。
注意

Spring Initializr 使用组和构件的名称来创建包名，例如：com.example.wingtiptoysdata。

Spring Boot 的版本可能高于 Azure 支持支持的版本。自动生成项目后，可以手动将 Spring Boot 版本更改为 Azure 支持的最高版本，可在 Spring-Versions-Mapping中找到。
指定前面列出的选项后，请选择 GENERATE。
出现提示时，将项目下载到本地计算机上的路径并提取文件。

现在，简单的 Spring Boot 应用程序已准备好进行编辑。

将 Spring Boot 应用程序配置为使用 Azure Spring Boot Starter

在应用的目录中找到 pom.xml 文件;例如：

C:\SpringBoot\wingtiptoysdata\pom.xml

-或-

/users/example/home/wingtiptoysdata/pom.xml
在文本编辑器中打开 pom.xml 文件，并将以下内容添加到 <dependencies> 元素：
```
<dependency>
  <groupId>com.azure.spring</groupId>
  <artifactId>spring-cloud-azure-starter-data-cosmos</artifactId>
</dependency>
```
注意

有关如何使用材料清单（BOM）管理 Spring Cloud Azure 库版本的详细信息，请参阅 Spring Cloud Azure 开发人员指南入门部分。
保存并关闭 pom.xml 文件。

将 Spring Boot 应用程序配置为使用 Azure Cosmos DB

在应用的资源目录中找到 application.properties 文件;例如：

C:\SpringBoot\wingtiptoysdata\src\main\resources\application.properties

-或-

/users/example/home/wingtiptoysdata/src/main/resources/application.properties

在文本编辑器中打开 application.properties 文件，并将以下行添加到该文件，并将示例值替换为数据库的相应属性：

# Specify the DNS URI of your Azure Cosmos DB.
spring.cloud.azure.cosmos.endpoint=https://contosoaccounttest.documents.azure.com:443/
spring.cloud.azure.cosmos.key=your-cosmosdb-account-key

# Specify the name of your database.
spring.cloud.azure.cosmos.database=contosoaccounttest
spring.cloud.azure.cosmos.populate-query-metrics=true

保存并关闭 application.properties 文件。

添加示例代码以实现基本数据库功能

在本部分中，你将创建两个 Java 类来存储用户数据。然后，修改主应用程序类以创建 User 类的实例并将其保存到数据库。

定义用于存储用户数据的基类

在与主应用程序 Java 文件相同的目录中创建一个名为 User.java 的新文件。

在文本编辑器中打开 User.java 文件，并将以下行添加到该文件，以定义在数据库中存储和检索值的泛型用户类：

package com.example.wingtiptoysdata;

import com.azure.spring.data.cosmos.core.mapping.Container;
import com.azure.spring.data.cosmos.core.mapping.PartitionKey;
import org.springframework.data.annotation.Id;

@Container(containerName = "mycollection")
public class User {
    @Id
    private String id;
    private String firstName;
    @PartitionKey
    private String lastName;
    private String address;

    public User() {

    }

    public User(String id, String firstName, String lastName, String address) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.address = address;
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    @Override
    public String toString() {
        return String.format("%s %s, %s", firstName, lastName, address);
    }
}

保存并关闭 User.java 文件。

定义数据存储库接口

在与主应用程序 Java 文件相同的目录中创建名为 UserRepository.java 的新文件。
在文本编辑器中打开 UserRepository.java 文件，并将以下行添加到该文件，以定义扩展默认 ReactiveCosmosRepository 接口的用户存储库界面：
```
package com.example.wingtiptoysdata;

import com.azure.spring.data.cosmos.repository.ReactiveCosmosRepository;
import org.springframework.stereotype.Repository;
import reactor.core.publisher.Flux;

@Repository
public interface UserRepository extends ReactiveCosmosRepository<User, String> {
    Flux<User> findByFirstName(String firstName);
}
```
ReactiveCosmosRepository 接口替换了启动器上一版本中的 DocumentDbRepository 接口。新接口提供用于基本保存、删除和查找操作的同步和反应 API。
保存并关闭 UserRepository.java 文件。

修改主应用程序类

在应用程序的包目录中找到主应用程序 Java 文件，例如：

C:\SpringBoot\wingtiptoysdata\src\main\java\com\example\wingtiptoysdata\WingtiptoysdataApplication.java

-或-

/users/example/home/wingtiptoysdata/src/main/java/com/example/wingtiptoysdata/WingtiptoysdataApplication.java

在文本编辑器中打开主应用程序 Java 文件，并将以下行添加到该文件：

package com.example.wingtiptoysdata;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.util.Assert;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.util.Optional;

@SpringBootApplication
public class WingtiptoysdataApplication implements CommandLineRunner {

    private static final Logger LOGGER = LoggerFactory.getLogger(WingtiptoysdataApplication.class);

    @Autowired
    private UserRepository repository;

    public static void main(String[] args) {
        SpringApplication.run(WingtiptoysdataApplication.class, args);
    }

    public void run(String... var1) {
        this.repository.deleteAll().block();
        LOGGER.info("Deleted all data in container.");

        final User testUser = new User("testId", "testFirstName", "testLastName", "test address line one");

        // Save the User class to Azure Cosmos DB database.
        final Mono<User> saveUserMono = repository.save(testUser);

        final Flux<User> firstNameUserFlux = repository.findByFirstName("testFirstName");

        //  Nothing happens until we subscribe to these Monos.
        //  findById won't return the user as user isn't present.
        final Mono<User> findByIdMono = repository.findById(testUser.getId());
        final User findByIdUser = findByIdMono.block();
        Assert.isNull(findByIdUser, "User must be null");

        final User savedUser = saveUserMono.block();
        Assert.state(savedUser != null, "Saved user must not be null");
        Assert.state(savedUser.getFirstName().equals(testUser.getFirstName()), "Saved user first name doesn't match");

        firstNameUserFlux.collectList().block();

        final Optional<User> optionalUserResult = repository.findById(testUser.getId()).blockOptional();
        Assert.isTrue(optionalUserResult.isPresent(), "Cannot find user.");

        final User result = optionalUserResult.get();
        Assert.state(result.getFirstName().equals(testUser.getFirstName()), "query result firstName doesn't match!");
        Assert.state(result.getLastName().equals(testUser.getLastName()), "query result lastName doesn't match!");

        LOGGER.info("findOne in User collection get result: {}", result.toString());
    }
}

保存并关闭主应用程序 Java 文件。

生成和测试应用

打开命令提示符并导航到 pom.xml 文件所在的文件夹;例如：

cd C:\SpringBoot\wingtiptoysdata

-或-

cd /users/example/home/wingtiptoysdata

使用以下命令生成并运行应用程序：

./mvnw clean

此命令在测试阶段自动运行应用程序。还可以使用：

./mvnw spring-boot:run

生成和测试输出后，控制台窗口会显示类似于以下示例的消息：

INFO 1365 --- [           main] c.e.w.WingtiptoysdataApplication         : Deleted all data in container.

... (omitting connection and diagnostics output) ...

INFO 1365 --- [           main] c.e.w.WingtiptoysdataApplication         : findOne in User collection get result: testFirstName testLastName, test address line one

这些输出消息指示数据已成功保存到 Azure Cosmos DB，然后再次检索。

清理资源

如果不打算继续使用此应用程序，请务必删除包含前面创建的 Azure Cosmos DB 的资源组。可以从 Azure 门户删除资源组。

后续步骤

若要了解有关 Spring 和 Azure 的详细信息，请继续阅读 Azure 上的 Spring 文档中心。

Azure 上的 Spring

通过