使用 Azure Cosmos DB NoSQL API 访问数据

项目
04/27/2023

本文介绍如何将 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 使开发人员能够使用 Spring Boot 应用程序轻松与 Azure Cosmos DB for NoSQL 集成。

先决条件

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

使用 Azure 门户创建 Azure Cosmos DB

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

浏览到Azure 门户并选择“创建资源”。
选择“数据库”，然后选择 Azure Cosmos DB。
在 “创建 Azure Cosmos DB 帐户 ”屏幕上，选择“ 用于 NoSQL 的 Azure Cosmos DB”。
在“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 接口替换上一 Starter 版本中的 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

通过