Spring Data 支援

本文說明如何搭配使用 Spring Cloud Azure 和 Spring Data。

Spring Data Azure Cosmos DB 支援

Azure Cosmos DB 是全域散發的資料庫服務，可讓開發人員使用各種標準 API 來處理數據，例如 SQL、MongoDB、Graph 和 Azure 數據表記憶體。

相依性設定

<dependency>
   <groupId>com.azure.spring</groupId>
   <artifactId>spring-cloud-azure-starter-data-cosmos</artifactId>
</dependency>

配置

注意

如果您使用安全性主體向 Microsoft Entra ID 進行驗證和授權，以存取 Azure 資源，請確定安全性主體已獲得足夠的許可權來存取 Azure 資源。 如需詳細資訊，請參閱 使用 Microsoft Entra ID授權存取權。

下表列出 spring-cloud-azure-starter-data-cosmos的可設定屬性：

財產	描述
spring.cloud.azure.cosmos.enabled	值，指出是否啟用 Azure Cosmos DB 服務。 預設值為 true。
spring.cloud.azure.cosmos.database	Azure Cosmos DB 資料庫標識符。
spring.cloud.azure.cosmos.endpoint	用來連線 Azure Cosmos DB 的 URI。
spring.cloud.azure.cosmos.key	用來連線 Azure Cosmos DB 的 PrivateKey。
spring.cloud.azure.cosmos.credential.client-certificate-password	憑證檔案的密碼。
spring.cloud.azure.cosmos.credential.client-certificate-path	使用 Azure 執行服務主體驗證時要使用的 PEM 憑證檔案路徑。
spring.cloud.azure.cosmos.credential.client-id	使用 Azure 執行服務主體驗證時要使用的用戶端識別碼。
spring.cloud.azure.cosmos.credential.client-secret	使用 Azure 執行服務主體驗證時要使用的客戶端密碼。
spring.cloud.azure.cosmos.credential.managed-identity-enabled	是否要啟用受控識別。 預設值為 false。
spring.cloud.azure.cosmos.credential.password	使用 Azure 執行使用者名稱/密碼驗證時要使用的密碼。
spring.cloud.azure.cosmos.credential.username	使用 Azure 執行使用者名稱/密碼驗證時要使用的用戶名稱。
spring.cloud.azure.cosmos.populate-query-metrics	值，指出是否要填入診斷字串和查詢計量。 預設值為 false。
spring.cloud.azure.cosmos.consistency-level	Azure Cosmos DB 的 一致性層級。

重要概念

下列清單顯示 Spring Data 支援的重要概念：

• Spring Data CrudRepository 和 ReactiveCrudRepository，其提供下列基本 CRUD 功能：

  • 儲存
  • findAll (查找全部)
  • 根據 ID 尋找一個項目
  • 全部刪除
  • 依標識碼刪除
  • 刪除實體

• Spring Data @Id 註釋。 有兩種方式可將網域類別中的欄位對應至 Azure Cosmos DB 檔的 id：

  • 使用 @Id為網域類別中的欄位加上批注。 此欄位將會對應至 Azure Cosmos DB 中的檔案 id。
  • 將此欄位的名稱設定為 id。 此欄位將會對應至 Azure Cosmos DB 中的檔案 id。

  注意

  如果套用這兩種方式，@Id 批注的優先順序較高。

• 自訂集合名稱。 根據預設，集合名稱會是使用者網域類別的類別名稱。 若要自定義它，請將批註 @Document(collection="myCustomCollectionName") 新增至您的網域類別，這就是全部。

• 支援 Azure Cosmos DB 分割區。 若要指定網域類別的欄位做為分割區索引鍵欄位，請使用 @PartitionKey標註它。 當您執行 CRUD 作業時，請指定分割區值。 如需更多範例，請參閱 GitHub 上的 AddressRepositoryIT.java。

• 支援 Spring Data 自訂查詢 find 作業。

• 支援 spring-boot-starter-data-rest。

• 支援網域類別中的清單和巢狀類型。

基本用法

使用私鑰來存取 Azure Cosmos DB

使用 spring-cloud-azure-starter-data-cosmos 連接 Azure Cosmos DB 最簡單的方式是使用主鍵。 新增下列屬性：

spring:
  cloud:
    azure:
      cosmos:
        key: ${AZURE_COSMOS_KEY}
        endpoint: ${AZURE_COSMOS_ENDPOINT}
        database: ${AZURE_COSMOS_DATABASE}

定義實體

在 Azure Cosmos DB 中將實體定義為檔，如下列範例所示：

@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);
    }
}

id 欄位將作為 Azure Cosmos DB 中文件的 id。 或者，您可以標註任何具有 @Id 的欄位，將它對應至檔案 id。

批註 @Container(containerName = "mycollection") 可用來在 Azure Cosmos DB 中指定檔的集合名稱。

建立存放庫

若要建立存放庫，請擴充 ReactiveCosmosRepository 介面，以提供 Spring Data 存放庫支援。

@Repository
public interface UserRepository extends ReactiveCosmosRepository<User, String> {
    Flux<User> findByFirstName(String firstName);
}

目前，ReactiveCosmosRepository 介面提供基本的儲存、刪除和尋找作業。 稍後將支援更多作業。

建立應用程式類別

下列範例會建立具有所有元件的應用程式類別：

@SpringBootApplication
public class CosmosSampleApplication implements CommandLineRunner {

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

    @Autowired
    private UserRepository repository;

    @Autowired
    private CosmosProperties properties;

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

    public void run(String... var1) {
        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());

    }

    @PostConstruct
    public void setup() {
        // For this example, remove all of the existing records.
        this.repository.deleteAll().block();
    }
}

此範例包含自動連接 UserRepository 介面，以支援儲存、刪除和尋找作業。

樣品

請參考 GitHub 上的相關資訊 azure-spring-boot-samples 。

除了使用 spring-cloud-azure-starter-data-cosmos 連結庫之外，您還可以直接針對更複雜的案例使用 azure-spring-data-cosmos 連結庫。 如需詳細資訊，請參閱 適用於 Azure Cosmos DB 的 Spring Data 用戶端連結庫。