适用于 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:8081
的 Azure 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 只有一个异步示例,没有同步示例。) ...等等...
注意
每个示例都是独立的,自行对自身进行设置并在完成后自行进行清理。 这些示例会发出多个调用以创建 CosmosContainer
或 CosmosAsyncContainer
。 每当执行此操作时,即会根据所创建的集合的性能层,对订阅收取使用 1 小时的费用。
数据库示例
sync 和 async 的数据库 CRUD 示例文件展示了如何执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 数据库,请参阅使用数据库、容器和项概念性文章。
集合示例
sync 和 async 的集合 CRUD 示例文件展示了如何执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 集合,请参阅使用数据库、容器和项概念性文章。
自动缩放集合示例
若要在运行这些示例之前了解有关自动缩放的详细信息,请查看以下说明,了解如何在帐户以及数据库和容器中启用自动缩放。
sync 和 async 的自动缩放数据库示例文件展示了如何执行以下任务。
任务 | API 参考 |
---|---|
创建具有指定自动缩放最大吞吐量的数据库 | CosmosClient.createDatabase CosmosAsyncClient.createDatabase |
sync 和 async 的自动缩放集合示例文件展示了如何执行以下任务。
任务 | API 参考 |
---|---|
创建具有指定自动缩放最大吞吐量的集合 | CosmosDatabase.createContainerIfNotExists CosmosAsyncDatabase.createContainerIfNotExists |
更改集合的已配置自动缩放最大吞吐量 | CosmosContainer.replaceThroughput CosmosAsyncContainer.replaceThroughput |
读取集合的自动缩放吞吐量配置 | CosmosContainer.readThroughput CosmosAsyncContainer.readThroughput |
分析存储集合示例
sync 和 async 的分析存储集合 CRUD 示例文件展示了如何执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 集合,请阅读有关 Azure Cosmos DB Synapse 和分析存储的内容。
任务 | API 参考 |
---|---|
创建集合 | CosmosDatabase.createContainerIfNotExists CosmosAsyncDatabase.createContainerIfNotExists |
项示例
sync 和 async 的文档 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 索引策略。
查询示例
sync 和 async 的查询示例文件展示了如何使用 SQL 查询语法执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 中的 SQL 查询引用,请参阅 Azure Cosmos DB 的 SQL 查询示例。
更改源示例
更改源处理器示例文件演示如何执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 中的更改源,请参阅读取 Azure Cosmos DB 更改源和更改源处理器。
任务 | API 参考 |
---|---|
基本的更改源功能 | ChangeFeedProcessor.changeFeedProcessorBuilder |
从头读取更改源 | ChangeFeedProcessorOptions.setStartFromBeginning() |
服务器端编程示例
存储过程示例文件演示如何执行以下任务。 若要在运行以下示例之前了解 Azure Cosmos DB 中的服务器端编程,请参阅存储过程、触发器和用户定义的函数。
任务 | API 参考 |
---|---|
创建存储过程 | CosmosScripts.createStoredProcedure |
执行存储过程 | CosmosStoredProcedure.execute |
删除存储过程 | CosmosStoredProcedure.delete |
后续步骤
正在尝试为迁移到 Azure Cosmos DB 进行容量计划? 可以使用有关现有数据库群集的信息进行容量规划。
- 如果只知道现有数据库群集中的 vCore 和服务器数量,请阅读使用 vCore 或 vCPU 估算请求单位
- 若知道当前数据库工作负载的典型请求速率,请阅读使用 Azure Cosmos DB 容量计划工具估算请求单位