使用 Azure Cosmos DB NoSQL API 存取數據

本文說明如何將 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 及 Table 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]。
喺Create an Azure Cosmos DB account時，選擇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 應用程式專案。作為替代選擇，你可以在 spring-cloud-azure-data-cosmos-sample 儲存庫中使用 azure-spring-boot-samples 樣本。然後，您可以直接跳到建置和測試您的應用程式。

瀏覽至 https://start.spring.io/。
指定下列選項：
- 使用 Java產生 Maven 專案。
- 請指定你的 Spring Boot 版本為 2.7.11。
- 指定應用程式的群組和工件名稱。
- 針對 Java 版本選取 17。
- 在相依性中新增 Azure 支援。
注意

Spring 初始化器使用群組名稱與工件名稱來建立套件名稱。例如： 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

在你的應用程式資源目錄中找到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 檔中心。

蔚藍之春

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-13