你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
CosmosContainer 类
- java.
lang. Object - com.
azure. cosmos. CosmosContainer
- com.
public class CosmosContainer
提供用于读取、删除和替换现有容器的同步方法 提供用于与子资源交互的方法， (项、脚本、冲突)
方法摘要
方法继承自 java.lang.Object
方法详细信息
createItem
public CosmosItemResponse
同步创建新项并返回其各自的 Cosmos 项响应。
Parameters:
Returns:
createItem
public CosmosItemResponse
同步创建新项，并在指定其他选项时返回其各自的 Cosmos 项响应。
分区键值将自动从项的内容中提取。
Parameters:
Returns:
createItem
public CosmosItemResponse
同步创建新项，并在指定其他选项时返回其各自的 Cosmos 项响应。
Parameters:
Returns:
deleteItem
public CosmosItemResponse
删除当前容器中的项。
Parameters:
Returns:
patchItem
public CosmosItemResponse
运行部分更新，以修改项的特定属性或字段，而不替换整个项。
CosmosPatchOperations cosmosPatchOperations = CosmosPatchOperations.create();
cosmosPatchOperations
.add("/departure", "SEA")
.increment("/trips", 1);
CosmosItemResponse<Passenger> response = cosmosContainer.patchItem(
passenger.getId(),
new PartitionKey(passenger.getId()),
cosmosPatchOperations,
Passenger.class);
Parameters:
Returns:
patchItem
public CosmosItemResponse
运行部分更新，以修改项的特定属性或字段，而不替换整个项。
CosmosPatchOperations cosmosPatchOperations = CosmosPatchOperations.create();
cosmosPatchOperations
.add("/departure", "SEA")
.increment("/trips", 1);
CosmosItemResponse<Passenger> response = cosmosContainer.patchItem(
passenger.getId(),
new PartitionKey(passenger.getId()),
cosmosPatchOperations,
Passenger.class);
Parameters:
Returns:
queryChangeFeed
public CosmosPagedIterable
使用 查询当前容器的更改源中的 CosmosChangeFeedRequestOptions项。
CosmosChangeFeedRequestOptions options = CosmosChangeFeedRequestOptions
.createForProcessingFromNow(FeedRange.forFullRange())
.allVersionsAndDeletes();
Iterable<FeedResponse<Passenger>> feedResponses = cosmosContainer.queryChangeFeed(options, Passenger.class)
.iterableByPage();
for (FeedResponse<Passenger> feedResponse : feedResponses) {
List<Passenger> results = feedResponse.getResults();
System.out.println(results);
}
可以通过再次调用 queryChangeFeed 来检索下一页，并使用从先前返回FeedResponse<T>的实例CosmosChangeFeedRequestOptions的延续标记创建的新实例。
Parameters:
Returns:
queryItems
public CosmosPagedIterable
查询当前容器中以 的形式 CosmosPagedIterable<T>返回结果的项。
CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
String query = "SELECT * FROM Passenger p WHERE (p.departure = @departure)";
List<SqlParameter> parameters = Collections.singletonList(new SqlParameter("@departure", "SEA"));
SqlQuerySpec sqlQuerySpec = new SqlQuerySpec(query, parameters);
Iterable<FeedResponse<Passenger>> queryResponses = cosmosContainer.queryItems(sqlQuerySpec, options, Passenger.class)
.iterableByPage();
for (FeedResponse<Passenger> feedResponse : queryResponses) {
List<Passenger> results = feedResponse.getResults();
System.out.println(results);
}
Parameters:
Returns:
queryItems
public CosmosPagedIterable
查询当前容器中以 的形式 CosmosPagedIterable<T>返回结果的项。
CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
String query = "SELECT * FROM Passenger WHERE Passenger.departure IN ('SEA', 'IND')";
Iterable<FeedResponse<Passenger>> queryResponses = cosmosContainer.queryItems(query, options, Passenger.class)
.iterableByPage();
for (FeedResponse<Passenger> feedResponse : queryResponses) {
List<Passenger> results = feedResponse.getResults();
System.out.println(results);
}
Parameters:
Returns:
readAllItems
public CosmosPagedIterable
读取以 的形式 CosmosPagedIterable<T>返回结果的逻辑分区的所有项。
CosmosPagedIterable<Passenger> passengers = cosmosContainer
.readAllItems(new PartitionKey(partitionKey), Passenger.class);
passengers.forEach(passenger -> {
System.out.println(passenger);
});
Parameters:
Returns:
readAllItems
public CosmosPagedIterable
读取以 的形式 CosmosPagedIterable<T>返回结果的逻辑分区的所有项。
CosmosPagedIterable<Passenger> passengers = cosmosContainer
.readAllItems(new PartitionKey(partitionKey), Passenger.class);
passengers.forEach(passenger -> {
System.out.println(passenger);
});
Parameters:
Returns:
readItem
public CosmosItemResponse
读取当前容器中的项，同时指定其他选项。 此操作用于根据容器的唯一标识符 (ID) 和分区键从容器中检索单个项。 readItem 操作使用特定项的唯一标识符提供对特定项的直接访问，该标识符由项的 ID 和分区键值组成。 此操作对于按已知项的 ID 和分区键检索已知项非常有效，无需进行复杂的查询。
Parameters:
Returns:
readItem
public CosmosItemResponse
读取当前容器中的项。 此操作用于根据容器的唯一标识符 (ID) 和分区键从容器中检索单个项。 readItem 操作使用特定项的唯一标识符提供对特定项的直接访问，该标识符由项的 ID 和分区键值组成。 此操作对于按已知项的 ID 和分区键检索已知项非常有效，无需进行复杂的查询。
// Read an item
try {
CosmosItemResponse<Passenger> response = cosmosContainer.readItem(
passenger.getId(),
new PartitionKey(passenger.getId()),
Passenger.class
);
Passenger passengerItem = response.getItem();
} catch (NotFoundException e) {
// catch exception if item not found
System.out.printf("Passenger with item id %s not found\n",
passenger.getId());
} catch (Exception e) {
System.out.println(e.getMessage());
}
// ...
Parameters:
Returns:
readMany
public FeedResponse
读取许多文档。 可用于在单个请求中读取具有特定 ID 和分区键的许多文档。 如果列表中缺少任何文档，则不会引发异常。
List<CosmosItemIdentity> itemIdentityList = new ArrayList<>();
itemIdentityList.add(new CosmosItemIdentity(new PartitionKey(passenger1Id), passenger1Id));
itemIdentityList.add(new CosmosItemIdentity(new PartitionKey(passenger2Id), passenger2Id));
FeedResponse<Passenger> passengerFeedResponse = cosmosContainer.readMany(itemIdentityList, Passenger.class);
for (Passenger passenger : passengerFeedResponse.getResults()) {
System.out.println(passenger);
}
Parameters:
Returns:
readMany
public FeedResponse
读取许多文档。 可用于在单个请求中读取具有特定 ID 和分区键的许多文档。 如果列表中缺少任何文档，则不会引发异常。
List<CosmosItemIdentity> itemIdentityList = new ArrayList<>();
itemIdentityList.add(new CosmosItemIdentity(new PartitionKey(passenger1Id), passenger1Id));
itemIdentityList.add(new CosmosItemIdentity(new PartitionKey(passenger2Id), passenger2Id));
FeedResponse<Passenger> passengerFeedResponse = cosmosContainer.readMany(itemIdentityList, Passenger.class);
for (Passenger passenger : passengerFeedResponse.getResults()) {
System.out.println(passenger);
}
Parameters:
Returns:
replaceItem
public CosmosItemResponse
将容器中的现有项替换为新项。 它执行项的完全替换，将其所有属性替换为新项的属性
CosmosItemResponse<Passenger> response = cosmosContainer.replaceItem(
newPassenger,
oldPassenger.getId(),
new PartitionKey(oldPassenger.getId()),
new CosmosItemRequestOptions());
Parameters:
Returns:
upsertItem
public CosmosItemResponse
在当前容器中插入 Cosmos 项。
Parameters:
Returns:
upsertItem
public CosmosItemResponse
在指定其他选项时插入项 Cosmos 同步项。
Parameters:
Returns:
upsertItem
public CosmosItemResponse
在指定其他选项时更新插入项 Cosmos 同步项。
Parameters:
Returns:
executeBulkOperations
public Iterable<>
批量执行操作的列表。
Parameters:
Returns:
executeBulkOperations
public Iterable<>
批量执行操作的列表。
Parameters:
Returns:
delete
public CosmosContainerResponse delete()
删除当前 cosmos 容器。
Returns:
delete
public CosmosContainerResponse delete(CosmosContainerRequestOptions options)
在指定其他选项（如 If-Match）时删除当前 Cosmos 容器。
Parameters:
Returns:
deleteAllItemsByPartitionKey
public CosmosItemResponse
删除容器中具有指定 partitionKey 值的所有项。 启动异步 Cosmos DB 后台操作，以删除容器中具有指定值的所有项。 异步 Cosmos DB 后台操作使用一定百分比的用户 RU 运行。
Parameters:
Returns:
deleteItem
public CosmosItemResponse
删除当前容器中的项。
try {
CosmosItemRequestOptions options = new CosmosItemRequestOptions();
CosmosItemResponse<Object> deleteItemResponse = cosmosContainer.deleteItem(
passenger.getId(),
new PartitionKey(passenger.getId()),
options
);
System.out.println(deleteItemResponse);
} catch (NotFoundException e) {
// catch exception if item not found
System.out.printf("Passenger with item id %s not found\n",
passenger.getId());
} catch (Exception e) {
System.out.println(e.getMessage());
}
Parameters:
Returns:
enableGlobalThroughputControlGroup
public void enableGlobalThroughputControlGroup(ThroughputControlGroupConfig groupConfig, GlobalThroughputControlConfig globalControlConfig)
使用全局控制模式启用吞吐量控制组。 定义的吞吐量限制将在不同的客户端之间共享。
ThroughputControlGroupConfig groupConfig =
new ThroughputControlGroupConfigBuilder()
.groupName("localControlGroup")
.targetThroughputThreshold(0.1)
.build();
GlobalThroughputControlConfig globalControlConfig =
this.client.createGlobalThroughputControlConfigBuilder(database.getId(), container.getId())
.setControlItemRenewInterval(Duration.ofSeconds(5))
.setControlItemExpireInterval(Duration.ofSeconds(10))
.build();
container.enableGlobalThroughputControlGroup(groupConfig, globalControlConfig);
Parameters:
enableLocalThroughputControlGroup
public void enableLocalThroughputControlGroup(ThroughputControlGroupConfig groupConfig)
使用本地控制模式启用吞吐量控制组。
ThroughputControlGroupConfig groupConfig =
new ThroughputControlGroupConfigBuilder()
.groupName("localControlGroup")
.targetThroughputThreshold(0.1)
.build();
container.enableLocalThroughputControlGroup(groupConfig);
Parameters:
executeCosmosBatch
public CosmosBatchResponse executeCosmosBatch(CosmosBatch cosmosBatch)
执行事务性批处理。
Parameters:
Returns:
如果事务批处理成功执行，则返回的响应中 返回 CosmosBatchResponse#getStatusCode 的值将设置为 200}。
如果事务批处理中的操作在执行期间失败，则不会提交批处理中的更改，并且失败操作的状态由 CosmosBatchResponse#getStatusCode 异常或由异常提供。 若要获取有关在发生某些用户错误（如冲突、未找到等）时失败的操作的信息，可以枚举响应。 这将返回 CosmosBatchOperationResult 与事务批处理中每个操作对应的实例，这些实例将按照将其添加到事务批处理的顺序返回。 对于与事务批处理中的操作对应的结果，请使用 CosmosBatchOperationResult#getStatusCode 访问操作的状态。 如果操作未执行或由于事务批处理中另一个操作失败而中止，则此字段的值将为 424;对于导致批处理中止的操作，此字段的值将指示失败的原因。
如果存在请求超时、消失、会话不可用、网络故障或服务以某种方式返回 5xx 等问题，则会引发异常，而不是返回 CosmosBatchResponse。
对返回的响应使用 CosmosBatchResponse#isSuccessStatusCode 以确保事务批处理成功。
executeCosmosBatch
public CosmosBatchResponse executeCosmosBatch(CosmosBatch cosmosBatch, CosmosBatchRequestOptions requestOptions)
执行事务性批处理。
Parameters:
Returns:
如果事务批处理成功执行，则返回的响应中 返回 CosmosBatchResponse#getStatusCode 的值将设置为 200}。
如果事务批处理中的操作在执行期间失败，则不会提交批处理中的更改，并且失败操作的状态由 CosmosBatchResponse#getStatusCode 异常或由异常提供。 若要获取有关在发生某些用户错误（如冲突、未找到等）时失败的操作的信息，可以枚举响应。 这将返回 CosmosBatchOperationResult 与事务批处理中每个操作对应的实例，这些实例将按照将其添加到事务批处理的顺序返回。 对于与事务批处理中的操作对应的结果，请使用 CosmosBatchOperationResult#getStatusCode 访问操作的状态。 如果操作未执行或由于事务批处理中另一个操作失败而中止，则此字段的值将为 424;对于导致批处理中止的操作，此字段的值将指示失败的原因。
如果存在请求超时、消失、会话不可用、网络故障或服务以某种方式返回 5xx 等问题，则会引发异常，而不是返回 CosmosBatchResponse。
对返回的响应使用 CosmosBatchResponse#isSuccessStatusCode 以确保事务批处理成功。
getFeedRanges
getId
public String getId()
获取当前容器 ID。
Returns:
getScripts
public CosmosScripts getScripts()
获取使用当前容器作为上下文的 Cosmos 脚本。
Returns:
openConnectionsAndInitCaches
@Deprecated
public void openConnectionsAndInitCaches()
已放弃
通过预热当前读取区域的缓存和连接来初始化容器。
注意：理想情况下，在任何工作负载之前，在应用程序初始化期间，只应调用此 API 一次。 如果出现任何暂时性错误，调用方应使用该错误并继续执行常规工作负荷。
openConnectionsAndInitCaches
@Deprecated
public void openConnectionsAndInitCaches(int numProactiveConnectionRegions)
已放弃
通过将缓存和连接预热到指定的主动连接区域的连接来初始化容器。 有关主动连接区域的详细信息，请参阅 getProactiveConnectionRegionsCount()
注意：理想情况下，在应用程序初始化期间，应在任何工作负载之前只调用此 API 一次。 如果出现任何暂时性错误，调用方应使用错误并继续常规工作负荷。
Parameters:
read
public CosmosContainerResponse read()
读取当前容器。
Returns:
read
public CosmosContainerResponse read(CosmosContainerRequestOptions options)
在指定其他选项（如 If-Match）时读取当前容器。
Parameters:
Returns:
readThroughput
public ThroughputResponse readThroughput()
获取当前容器的吞吐量。
try {
ThroughputResponse throughputResponse = cosmosContainer.readThroughput();
System.out.println(throughputResponse);
} catch (CosmosException ce) {
ce.printStackTrace();
} catch (Exception e) {
e.printStackTrace();
}
Returns:
replace
public CosmosContainerResponse replace(CosmosContainerProperties containerProperties)
替换当前容器属性。
Parameters:
Returns:
replace
public CosmosContainerResponse replace(CosmosContainerProperties containerProperties, CosmosContainerRequestOptions options)
在指定其他选项（如 If-Match）时替换当前容器属性。
Parameters:
Returns:
replaceThroughput
public ThroughputResponse replaceThroughput(ThroughputProperties throughputProperties)
设置当前容器的吞吐量。
ThroughputProperties throughputProperties =
ThroughputProperties.createAutoscaledThroughput(1000);
try {
ThroughputResponse throughputResponse =
cosmosContainer.replaceThroughput(throughputProperties);
System.out.println(throughputResponse);
} catch (CosmosException ce) {
ce.printStackTrace();
} catch (Exception e) {
e.printStackTrace();
}
Parameters:
Returns:
适用于
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈