使用 Azure Cosmos DB NoSQL API 存取數據

發行項
04/23/2024

本文說明如何將 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 （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 會 使用 Group 和 Artifact 名稱來建立套件名稱;例如： com.example.wingtiptoysdata。

Spring Boot 的版本可能高於 Azure 支援支援支援的版本。自動產生項目之後，您可以手動將 Spring Boot 版本變更為 Azure 所支援的最高版本，您可以在 Spring-Versions-Mapping 中找到該版本。
當您指定先前列出的選項時，請選取 [ 產生]。
出現提示時，請將專案下載到本機計算機上的路徑，並解壓縮檔案。

您的簡單 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

在應用程式的 resources 目錄中找出 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/

# 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

使用 Azure Cosmos DB NoSQL API 存取數據

必要條件

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

使用 Spring Initializr 建立 Spring Boot 應用程式

設定 Spring Boot 應用程式以使用 Azure Spring Boot Starter

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

新增範例程式代碼以實作基本資料庫功能

定義用來儲存用戶數據的基類

定義數據存放庫介面

修改主要應用程式類別

建置和測試您的應用程式

清除資源

下一步

更多資源

意見反應

意見反應

其他資源

使用 Azure Cosmos DB NoSQL API 存取數據

必要條件

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

使用 Spring Initializr 建立 Spring Boot 應用程式

設定 Spring Boot 應用程式以使用 Azure Spring Boot Starter

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

新增範例程式代碼以實作基本資料庫功能

定義用來儲存用戶數據的基類

定義數據存放庫介面

修改主要應用程式類別

建置和測試您的應用程式

清除資源

下一步

更多資源

意見反應

意見反應

其他資源

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