共用方式為

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 和數據表。

本指南將逐步引導您瞭解 Azure Spring Data Azure Cosmos DB SDK、支援的功能、疑難解答和已知問題的概念。 如需下列概念和程式代碼範例的詳細資訊，請參閱適用於 Azure Cosmos DB SDK 的 Spring Data 自述檔案。

版本支持原則

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 Spring Data Azure Cosmos DB 的詳細資訊，請參閱 應該使用哪個版本的 Azure Spring Data for Azure Cosmos DB？。

開始使用

將套件包含進去

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

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

先決條件

只有在您打算使用記錄時，才需要 SLF4J，同時下載 SLF4J 系結，這會連結 SLF4J API 與您選擇的記錄實作。 如需詳細資訊，請參閱 SLF4J 使用者手動。

設定和自定義組態類別

若要設置配置類別，您必須擴充 AbstractCosmosConfiguration。 如需詳細資訊，請參閱 安裝程式組態類別。

您可以藉由提供 DirectConnectionConfig 或 GatewayConnectionConfig 或兩者來自訂 Azure Spring Data Azure Cosmos DB SDK 所使用的基礎 CosmosAsyncClient，然後將它們提供給 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 批注自動產生標識符。 如需詳細資訊，請參閱 識別元自動產生一節，。

SpEL 運算式和自訂容器名稱

根據預設，容器名稱會是使用者網域類別的類別名稱。 若要自定義，請將 @Container(containerName="myCustomContainerName") 批註新增至網域類別。 如需詳細資訊，請參閱 SpEL 運算式與自訂容器名稱一節。

自定義索引原則

根據預設，Azure 服務會設定 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 支援特定容器的樂觀鎖定，這表示如果項目同時被另一個進程修改，則根據項目的上傳/刪除操作將會失敗，並引發例外狀況。 如需詳細資訊，請參閱 樂觀式鎖定一節。

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

Azure-spring-data-cosmos 支援 Spring Data 自定義查詢，例如，findByAFieldAndBField之類的尋找作業。 它也支援 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 支援多資料庫組態，包括「多個資料庫帳戶」和「具有多個資料庫的單一帳戶」。 如需完整的代碼段，請參閱 多資料庫組態一節。

故障排除

常規

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

若要建議可進行的新功能或變更，請以您針對 Bug 的相同方式提出問題。

啟用客戶端記錄

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

例子

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

多資料庫帳戶

如需完整的範例專案，請參閱 多資料庫範例專案。

具有多資料庫的單一帳戶

如需完整的範例專案，請參閱單一帳戶配合多資料庫的範例專案 。

後續步驟

貢獻

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

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

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

印象