适用于 NoSQL 的 Azure Cosmos DB: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 Cosmos DB 免费层帐户,你将在帐户中获得前 1000 RU/s 的免费吞吐量和 25 GB 的免费存储。 还可以使用 URI 为 https://localhost:8081Azure Cosmos DB 模拟器。 有关在模拟器中使用的密钥,请参阅对请求进行身份验证

azure-cosmos-java-sql-api-samples GitHub 存储库中包含可对 Azure Cosmos DB 资源执行 CRUD 操作和其他常见操作的最新示例应用程序。 本文将提供:

  • 每个示例 Java项目文件中各项任务的链接。
  • 指向相关的 API 参考内容的链接。

先决条件

需要以下条件才能运行此示例应用程序:

  • Java 开发工具包 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

才能使示例可以对你的帐户进行读/写访问。

若要运行示例,请指定其 Main 类

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 只有一个异步示例,没有同步示例。) ...等等...

注意

每个示例都是独立的,自行对自身进行设置并在完成后自行进行清理。 这些示例会发出多个调用以创建 CosmosContainerCosmosAsyncContainer。 每当执行此操作时,即会根据所创建的集合的性能层,对订阅收取使用 1 小时的费用。

数据库示例

syncasync 的数据库 CRUD 示例文件展示了如何执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 数据库,请参阅使用数据库、容器和项概念性文章。

任务 API 参考
创建数据库 CosmosClient.createDatabaseIfNotExists
CosmosAsyncClient.createDatabaseIfNotExists
按 ID 读取数据库 CosmosClient.getDatabase
CosmosAsyncClient.getDatabase
读取所有数据库 CosmosClient.readAllDatabases
CosmosAsyncClient.readAllDatabases
删除数据库 CosmosDatabase.delete
CosmosAsyncDatabase.delete

集合示例

syncasync 的集合 CRUD 示例文件展示了如何执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 集合,请参阅使用数据库、容器和项概念性文章。

任务 API 参考
创建集合 CosmosDatabase.createContainerIfNotExists
CosmosAsyncDatabase.createContainerIfNotExists
更改集合的已配置性能 CosmosContainer.replaceThroughput
CosmosAsyncContainer.replaceProvisionedThroughput
按 ID 获取集合 CosmosDatabase.getContainer
CosmosAsyncDatabase.getContainer
读取数据库中的所有集合 CosmosDatabase.readAllContainers
CosmosAsyncDatabase.readAllContainers
删除集合 CosmosContainer.delete
CosmosAsyncContainer.delete

自动缩放集合示例

若要在运行这些示例之前了解有关自动缩放的详细信息,请查看以下说明,了解如何在帐户以及数据库和容器中启用自动缩放。

syncasync 的自动缩放数据库示例文件展示了如何执行以下任务。

任务 API 参考
创建具有指定自动缩放最大吞吐量的数据库 CosmosClient.createDatabase
CosmosAsyncClient.createDatabase

syncasync 的自动缩放集合示例文件展示了如何执行以下任务。

任务 API 参考
创建具有指定自动缩放最大吞吐量的集合 CosmosDatabase.createContainerIfNotExists
CosmosAsyncDatabase.createContainerIfNotExists
更改集合的已配置自动缩放最大吞吐量 CosmosContainer.replaceThroughput
CosmosAsyncContainer.replaceThroughput
读取集合的自动缩放吞吐量配置 CosmosContainer.readThroughput
CosmosAsyncContainer.readThroughput

分析存储集合示例

syncasync 的分析存储集合 CRUD 示例文件展示了如何执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 集合,请阅读有关 Azure Cosmos DB Synapse 和分析存储的内容。

任务 API 参考
创建集合 CosmosDatabase.createContainerIfNotExists
CosmosAsyncDatabase.createContainerIfNotExists

项示例

syncasync 的文档 CRUD 示例文件展示了如何执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 文档,请参阅使用数据库、容器和项概念性文章。

注意

对特定项执行操作时,必须指定分区键。

任务 API 参考
创建文档 CosmosContainer.createItem
CosmosAsyncContainer.createItem
按 ID 读取文档 CosmosContainer.readItem
CosmosAsyncContainer.readItem
查询文档 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
替换文档 CosmosContainer.replaceItem
CosmosAsyncContainer.replaceItem
更新插入文档 CosmosContainer.upsertItem
CosmosAsyncContainer.upsertItem
删除文档 CosmosContainer.deleteItem
CosmosAsyncContainer.deleteItem
使用条件 ETag 检查替换文档 CosmosItemRequestOptions.setIfMatchETag (sync)
CosmosItemRequestOptions.setIfMatchETag (async)
仅当文档已更改时读取文档 CosmosItemRequestOptions.setIfNoneMatchETag (sync)
CosmosItemRequestOptions.setIfNoneMatchETag (async)
部分文档更新 CosmosContainer.patchItem
批量文档更新 批处理示例
事务性批处理 批处理示例

索引示例

集合 CRUD 示例文件演示如何执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 中的索引,请参阅索引策略索引类型索引路径概念文章。

任务 API 参考
在索引中包括指定的文档路径 IndexingPolicy.IncludedPaths
从索引中排除指定的文档路径 IndexingPolicy.ExcludedPaths
创建组合索引 IndexingPolicy.setCompositeIndexes
CompositePath
创建地理空间索引 IndexingPolicy.setSpatialIndexes
SpatialSpec
SpatialType

有关索引的详细信息,请参阅 Azure Cosmos DB 索引策略

查询示例

syncasync 的查询示例文件展示了如何使用 SQL 查询语法执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 中的 SQL 查询引用,请参阅 Azure Cosmos DB 的 SQL 查询示例

任务 API 参考
查询所有文档 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
使用 == 查询等式 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
使用 != 和 NOT 查询不等式 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
使用 >、<、>=、<= 等范围运算符进行查询 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
使用范围运算符对字符串进行查询 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
使用 ORDER BY 进行查询 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
使用 DISTINCT 查询 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
使用聚合函数进行查询 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
使用子文档 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
使用文档内联接进行查询 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
使用字符串、数学和数组运算符进行查询 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
使用 SqlQuerySpec 的参数化 SQL 进行查询 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
使用显式分页进行查询 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems
并行查询已分区集合 CosmosContainer.queryItems
CosmosAsyncContainer.queryItems

更改源示例

更改源处理器示例文件演示如何执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 中的更改源,请参阅读取 Azure Cosmos DB 更改源更改源处理器

任务 API 参考
基本的更改源功能 ChangeFeedProcessor.changeFeedProcessorBuilder
从头读取更改源 ChangeFeedProcessorOptions.setStartFromBeginning()

服务器端编程示例

存储过程示例文件演示如何执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 中的服务器端编程,请参阅存储过程、触发器和用户定义的函数

任务 API 参考
创建存储过程 CosmosScripts.createStoredProcedure
执行存储过程 CosmosStoredProcedure.execute
删除存储过程 CosmosStoredProcedure.delete

后续步骤

正在尝试为迁移到 Azure Cosmos DB 进行容量计划? 可以使用有关现有数据库群集的信息进行容量规划。