Azure Cosmos DB 開發人員指南

Azure Spring Data for Azure Cosmos DB 提供 適用於 Azure Cosmos DB for NoSQL的 Spring Data 支援。 Azure Cosmos DB 是一項全球分散式資料庫服務，開發者可透過多種標準 API 如 SQL、MongoDB、Cassandra、Graph 和 Table 來處理資料。

本指南說明 Azure Spring Data Azure Cosmos DB SDK 的概念、支援功能、故障排除及已知問題。 欲了解更多關於這些概念與程式碼範例，請參閱 Spring Data for Azure Cosmos DB SDK 說明文件。

版本支持原則

Spring Boot 版本支援

此項目支援多個 Spring Boot 版本。 如需詳細資訊，請參閱 Spring Boot 支援原則。 Maven 使用者可以從專案繼承 spring-boot-starter-parent ，取得相依管理區塊，讓 Spring 管理相依的版本。 如需詳細資訊，請參閱 Spring Boot 版本支援。

Spring Data 版本支援

此專案支援不同 spring-data-commons 版本。 如需詳細資訊，請參閱 Spring Data Version Support。

要使用的 Azure Spring Data Azure Cosmos DB 版本

Azure Spring Data Azure Cosmos DB 函式庫支援多個版本的 Spring Boot 與 Spring Cloud。 如需瞭解在 Spring Boot 和 Spring Cloud 中應使用哪個版本的適用於 Azure Cosmos DB 的 Azure Spring Data，請參閱我應該使用哪個版本的適用於 Azure Cosmos DB 的 Azure Spring Data？

開始

將套件包含進去

如果您使用 Maven，請新增下列相依性。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-spring-data-cosmos</artifactId>
    <version>LATEST</version>
</dependency>

先決條件

只有在你打算使用日誌記錄時，才需要 SLF4J。 另外下載 SLF4J 綁定檔，它能將 SLF4J API 與你選擇的日誌實作連結起來。 如需詳細資訊，請參閱 SLF4J 使用者手動。

設定和自定義組態類別

要設定配置類別，擴展 AbstractCosmosConfiguration。 如需詳細資訊，請參閱 安裝程式組態類別。

您可以自訂 Azure Spring Data Azure Cosmos DB SDK 所使用的底層 CosmosAsyncClient，方法是提供 DirectConnectionConfig、GatewayConnectionConfig 或同時提供兩者，再將其交給 CosmosClientBuilder。 完整範例請造訪 自訂配置區塊。

實體設定

你可以在 Azure Cosmos DB 中定義一個簡單的實體作為項目。 透過添加 @Container 註解並指定與容器相關的屬性來定義實體。 如需詳細資訊，請參閱 定義實體。

容器註解支援指定容器名稱、 請求單元 （RU）、存活時間、 建立具自動擴展吞吐量的容器、 巢狀分割鍵支援及其他容器屬性。

存放庫設定

Azure Spring Data Azure Cosmos DB 支援 ReactiveCrudRepository （異步 API） 和 CrudRepository （同步 API），其提供下列基本 CRUD 功能：

  • 保存 / 拯救
  • findAll (查找全部)
  • 根據 ID 尋找一個項目
  • 全部刪除
  • 根據 ID 刪除
  • 刪除實體

您可以擴充 CosmosRepository（適用於同步 API 支援）或 ReactiveCosmosRepository（適用於異步 API 支援），以設定應用程式的 Spring Data 存放庫。 如需詳細資訊，請參閱 建立存放庫。

Azure Spring Data Azure Cosmos DB 支援在存放庫中使用 @Query 指定帶註釋的查詢。 如需詳細資訊，請參閱 QueryAnnotation：在存放庫中使用批注查詢。

Spring 數據批注

Spring Data @Id 註解

你可以用多種方式映射一個域類別中的欄位到 。id 如需詳細資訊，請參閱第 節 spring 資料識別碼註釋代碼。

標識碼自動產生

Azure Spring Data Azure Cosmos DB 支援使用@GeneratedValue註解自動產生 ID。 如需詳細資訊，請參閱 識別元自動產生一節，。

SpEL 運算式和自訂容器名稱

預設情況下，容器名稱是使用者網域類別的類別名稱。 要自訂容器名稱，請在網域類別中加入 @Container(containerName="myCustomContainerName") 註解。 如需詳細資訊，請參閱 SpEL 運算式與自訂容器名稱一節。

自定義索引原則

預設情況下，Azure 服務會設定 IndexingPolicy. 若要自訂 IndexingPolicy，請將 @CosmosIndexingPolicy 註解加入網域類別。 如需詳細資訊，請參閱 索引編製原則一節。

唯一鍵政策

Azure Spring Data Azure Cosmos DB 支援藉由將 @CosmosUniqueKeyPolicy 註解加入網域類別，在容器上設定 UniqueKeyPolicy。 如需詳細資訊，請參閱 唯一索引鍵原則一節。

Azure Cosmos DB 磁碟分區

Azure-spring-data-cosmos 支援 Azure Cosmos DB 磁碟分區。

若要指定領域類別中的欄位作為分割鍵欄位，請用 @PartitionKey來註解。

執行 CRUD 操作時，請指定你的分割值。

如需詳細資訊，請參閱這裡 測試一節。

樂觀鎖定

Azure-spring-data-cosmos 支援特定容器的樂觀鎖定功能。 這項支援表示，以項目為單位執行 upsert 和刪除時，如果另一個程序修改了該項目，作業就會因引發例外而失敗。 如需詳細資訊，請參閱 樂觀式鎖定一節。

Spring Data 自定義查詢、可分頁和排序

Azure-spring-data-cosmos 支援 Spring Data 自訂查詢，例如像 findByAFieldAndBField 這樣的 find 作業。 它也支援 Spring Data Pageable、Slice 和 Sort。 欲了解更多資訊，請參閱 查詢、可分頁及排序部分。

透過 Spring Data Cosmos 使用 Azure Cosmos DB Java SDK

Azure-spring-data-cosmos 支援使用 Azure Cosmos DB Java SDK。 你可以透過 ApplicationContext 取得 CosmosClient 或 CosmosAsyncClient Bean，並執行 Azure Cosmos DB Java SDK 所支援的任何作業。 如需詳細資訊，請參閱透過 Spring Data Cosmos 使用 Azure Cosmos 用戶端 一節。

Spring Data REST

Azure-spring-data-cosmos 支援 Spring Data REST。 如需詳細資訊，請參閱 Azure Spring Data Azure Cosmos DB REST API 一節。

審計

Azure-spring-data-cosmos 支援使用標準 Spring Data 註解對資料庫實體上的欄位進行稽核。 如需詳細資訊，請參閱 Spring Data Azure Cosmos DB 稽核一節。

多資料庫組態

Azure-spring-data-cosmos 支援多資料庫配置，包括 多個資料庫帳號 及 單一帳號擁有多個資料庫。 如需完整的代碼段，請參閱 多資料庫組態一節。

故障排除

一般

如果你遇到錯誤，請 在這裡提出問題。

要建議新功能或變更，請像處理錯誤一樣提交問題。

啟用客戶端記錄

Azure-spring-data-cosmos 使用 SLF4j 作為記錄外觀，可支援登入 log4j 和 logback 等熱門記錄架構。 如需詳細資訊，請參閱 啟用客戶端記錄一節。

例子

如需完整的範例專案，請參閱 範例專案。

多資料庫帳戶

完整範例專案請參見 多資料庫範例專案。

具有多資料庫的單一帳戶

完整範例專案請參閱 多個資料庫的單一帳戶範例專案。

後續步驟

貢獻

此項目歡迎參與和建議。 大部分的貢獻都要求您同意 參與者許可協議（CLA），聲明您有權且確實授與我們使用您貢獻的權利。

當您提交 Pull Request 時，CLA-Bot 會自動判斷您是否需要提供 CLA 並適當地標示該 PR，例如標籤、註解。 只要遵循 Bot 所提供的指示即可。 您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案已採用 Microsoft開源行為準則。 如需詳細資訊，請參閱 規範常見問題，或與任何其他問題或意見連絡 opencode@microsoft.com。

  • Last updated on