使用 Azure Cosmos DB NoSQL API 存取數據

發行項
01/20/2025

本文說明如何將 Spring Cloud Azure Starter for Spring Data for Azure Cosmos DB 新增至自定義應用程式。此入門版可讓您使用 Spring Data 和適用於 NoSQL 的 Azure Cosmos DB，將數據儲存在 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 應用程式，輕鬆地與適用於 NoSQL 的 Azure Cosmos DB 整合。

先決條件

Azure 訂用帳戶 - 免費建立一個。
Java Development Kit JDK8 或以上版本。
Apache Maven。
Azure CLI。

使用 Azure 入口網站建立 Azure Cosmos DB

使用下列步驟來建立 Azure Cosmos DB 實例：

流覽至 Azure 入口網站，然後選取 [建立資源]。
選取 [資料庫]，然後選取 [Azure Cosmos DB]。
在 [建立 Azure Cosmos DB 帳戶 頁面上，選取 [Azure Cosmos DB 以支援 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 會使用 Group 和 Artifact 名稱來建立套件名稱;例如：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>
```
注意

如需如何使用材料帳單來管理 Spring Cloud Azure 連結庫版本的詳細資訊，請參閱 Spring Cloud Azure 開發人員指南的用戶入門一節。
儲存並關閉 pom.xml 檔案。

設定 Spring Boot 應用程式以使用 Azure Cosmos DB

在應用程式的資源目錄中，找出 application.properties 檔案;例如：

C：\SpringBoot\wingtiptoysdata\src\main\rresources\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 檔中心。

蔚藍之春

共用方式為