Azure Cosmos DB for NoSQL：Java SDK v4 範例
適用於：
NoSQL
重要
若要深入了解 Java SDK v4，請檢視 Azure Cosmos DB Java SDK v4 版本資訊、Maven 存放庫、Azure Cosmos DB Java SDK v4 效能秘訣和 Azure Cosmos DB Java SDK v4 疑難排解指南。 如果您目前使用的版本比 v4 舊，請參閱遷移至 Azure Cosmos DB Java SDK v4 指南，以取得升級至 v4 的協助。
重要
如果您沒有 Azure 訂用帳戶，請在開始之前先建立 Azure 免費帳戶。
- 您可以 啟用 Visual Studio 訂閱者權益：您的 Visual Studio 訂用帳戶每個月都會提供額度，供您用在 Azure 付費服務。
您可以免費試用 Azure Cosmos DB，不需 Azure 訂用帳戶，也不需要承諾用量。 或者，您可以建立 Azure Cosmos DB 免費層帳戶，免費使用前 1000 RU/秒和 25 GB 的儲存體。 您也可以搭配 https://localhost:8081 的 URI 使用 Azure Cosmos DB 模擬器。 如需要搭配模擬器使用的金鑰，請參閱驗證要求。
azure-cosmos-java-sql-api-samples GitHub 存放庫中包含可對 Azure Cosmos DB 資源執行 CRUD 作業和其他常見作業的最新範例應用程式。 本文提供：
- 每個範例 Java 專案檔中各項工作的連結。
- 相關 API 參考內容的連結。
先決條件
執行此範例應用程式需要下列項目：
- Java Development Kit 8
- Azure Cosmos DB Java SDK v4
您可選擇使用 Maven 來取得最新的 Azure Cosmos DB Java SDK v4 二進位檔，以使用於您的專案中。 Maven 會自動加入任何必要的相依性。 否則，您可以直接下載 pom.xml 檔案中列出的相依性，並將它們加入至您的組建路徑。
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-cosmos</artifactId>
<version>LATEST</version>
</dependency>
執行範例應用程式
複製範例存放庫：
$ git clone https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples.git
$ cd azure-cosmos-java-sql-api-samples
您可以使用 IDE (Eclipse、IntelliJ 或 VS Code) 或從命令列使用 Maven 來執行範例。
必須設定這些環境變數
ACCOUNT_HOST=your account hostname;ACCOUNT_KEY=your account primary key
才能將您帳戶的讀取/寫入存取權授與範例。
若要執行範例，請指定其主要類別
com.azure.cosmos.examples.sample.synchronicity.MainClass
其中，sample.synchronicity.MainClass 可以是
- crudquickstart.sync.SampleCRUDQuickstart
- crudquickstart.async.SampleCRUDQuickstartAsync
- indexmanagement.sync.SampleIndexManagement
- indexmanagement.async.SampleIndexManagementAsync
- storedprocedure.sync.SampleStoredProcedure
- storedprocedure.async.SampleStoredProcedureAsync
- changefeed.SampleChangeFeedProcessor (Changefeed只有一個非同步範例，沒有同步範例。)...等等
注意
每個範例都各自獨立，會自己設定，並於完成後自行清理。 這些範例會發出多個呼叫來建立 CosmosContainer 或 CosmosAsyncContainer。 每當執行此動作時，即會根據所建立集合的效能層，對您的訂用帳戶計入 1 小時的使用費。
資料庫範例
同步和非同步的資料庫 CRUD 範例檔案會顯示如何執行下列工作。 若要在執行下列範例之前，先了解 Azure Cosmos DB 資料庫，請參閱使用資料庫、容器和項目概念文章。
集合範例
同步和非同步的集合 CRUD 範例檔案會顯示如何執行下列工作。 若要在執行下列範例之前，先了解 Azure Cosmos DB 集合，請參閱使用資料庫、容器和項目概念文章。
自動調整集合範例
若要在執行這些範例之前深入了解自動調整功能，請參閱這些指示，以在您的帳戶和資料庫和容器中啟用自動調整。
同步和非同步的自動調整資料庫範例檔案會顯示如何執行下列工作。
| Task | API 參考 |
|---|---|
| 以指定的自動調整最大輸送量建立資料庫 | CosmosClient.createDatabase CosmosAsyncClient.createDatabase |
| Task | API 參考 |
|---|---|
| 以指定的自動調整最大輸送量建立集合 | CosmosDatabase.createContainerIfNotExists CosmosAsyncDatabase.createContainerIfNotExists |
| 變更集合上已設定的自動調整最大輸送量 | CosmosContainer.replaceThroughput CosmosAsyncContainer.replaceThroughput |
| 讀取集合的自動調整輸送量設定 | CosmosContainer.readThroughput CosmosAsyncContainer.readThroughput |
分析儲存體集合範例
同步和非同步的分析儲存體集合 CRUD 範例檔案會顯示如何執行下列工作。 若要在執行下列範例之前，先了解 Azure Cosmos DB 集合，請參閱 Azure Cosmos DB Synapse 和分析存放區。
| Task | API 參考 |
|---|---|
| 建立集合 | CosmosDatabase.createContainerIfNotExists CosmosAsyncDatabase.createContainerIfNotExists |
項目範例
同步和非同步的文件 CRUD 範例檔案會顯示如何執行下列工作。 若要在執行下列範例之前，先了解 Azure Cosmos DB 文件，請參閱使用資料庫、容器和項目概念文章。
注意
針對特定項目執行作業時，您必須指定分割區索引鍵。
| Task | API 參考 |
|---|---|
| 建立文件 | CosmosContainer.createItem CosmosAsyncContainer.createItem |
| 依識別碼讀取文件 | CosmosContainer.readItem CosmosAsyncContainer.readItem |
| 查詢文件 | CosmosContainer.queryItems CosmosAsyncContainer.queryItems |
| 取代文件 | CosmosContainer.replaceItem CosmosAsyncContainer.replaceItem |
| Upsert 文件 | CosmosContainer.upsertItem CosmosAsyncContainer.upsertItem |
| 刪除文件 | CosmosContainer.deleteItem CosmosAsyncContainer.deleteItem |
| 以條件式 ETag 檢查取代文件 | CosmosItemRequestOptions.setIfMatchETag (同步) CosmosItemRequestOptions.setIfMatchETag (非同步) |
| 僅在文件變更時才讀取文件 | CosmosItemRequestOptions.setIfNoneMatchETag (同步) CosmosItemRequestOptions.setIfNoneMatchETag (非同步) |
| 部分文件更新 | CosmosContainer.patchItem |
| 大量文件更新 | 大量範例 |
| 交易式批次 | 批次範例 |
索引範例
集合 CRUD 範例檔案會說明如何執行下列工作。 若要在執行下列範例之前先了解 Azure Cosmos DB 中的索引功能，請參閱索引原則、索引類型及索引路徑概念性文章。
| Task | API 參考 |
|---|---|
| 在索引中包含指定的文件路徑 | IndexingPolicy.IncludedPaths |
| 從索引中排除指定的文件路徑 | IndexingPolicy.ExcludedPaths |
| 建立複合式索引 | IndexingPolicy.setCompositeIndexes CompositePath |
| 建立地理空間索引 | IndexingPolicy.setSpatialIndexes SpatialSpec SpatialType |
如需索引編製的詳細資訊，請參閱 Azure Cosmos DB 編製索引原則。
查詢範例
同步和非同步的查詢範例檔案會顯示如何使用 SQL 查詢文法來執行下列工作。 若要在執行下列範例之前先了解 Azure Cosmos DB 中的 SQL 查詢參考，請參閱適用於 Azure Cosmos DB 的 SQL 查詢範例。
變更摘要範例
變更摘要處理器範例檔案會說明如何執行下列工作。 若要在執行下列範例之前先了解 Azure Cosmos DB 中的變更摘要，請參閱讀取 Azure Cosmos DB 變更摘要和變更摘要處理器。
| Task | API 參考 |
|---|---|
| 基本變更摘要功能 | ChangeFeedProcessor.changeFeedProcessorBuilder |
| 從頭開始讀取變更摘要 | ChangeFeedProcessorOptions.setStartFromBeginning() |
伺服器端程式設計範例
預存程序範例檔案會說明如何執行下列工作。 若要在執行下列範例之前先了解 Azure Cosmos DB 中的伺服器端程式設計，請參閱預存程序、觸發程序和使用者定義函式。
| Task | API 參考 |
|---|---|
| 建立預存程序 | CosmosScripts.createStoredProcedure |
| 執行預存程序 | CosmosStoredProcedure.execute |
| 刪除預存程序 | CosmosStoredProcedure.delete |
下一步
正在嘗試為遷移至 Azure Cosmos DB 進行容量規劃嗎？ 您可以使用現有資料庫叢集的相關資訊進行容量規劃。
- 如果您知道現有資料庫叢集中的虛擬核心和伺服器數目，請參閱使用虛擬核心或 vCPU 來估計要求單位
- 如果您知道目前資料庫工作負載的一般要求率，請參閱使用 Azure Cosmos DB 容量規劃工具來估計要求單位