你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
CosmosClientBuilder 类
- java.
lang. Object - com.
azure. cosmos. CosmosClientBuilder
- com.
实现
public class CosmosClientBuilder
implements TokenCredentialTrait<CosmosClientBuilder>, AzureKeyCredentialTrait<CosmosClientBuilder>, EndpointTrait<CosmosClientBuilder>
用于生成 CosmosAsyncClient 和 CosmosClient 实例的帮助程序类，作为 Azure Cosmos 数据库服务的逻辑表示形式。
CosmosAsyncClient 和 CosmosClient 是线程安全的。 建议在应用程序的生存期内维护 CosmosClient 或 CosmosAsyncClient 的单个实例，从而实现高效的连接管理和性能。 CosmosAsyncClient 和 CosmosClient 初始化是繁重的操作 - 不要使用初始化 CosmosAsyncClient 或 CosmosClient 实例作为凭据或网络连接验证。
生成客户端时，endpoint () 和密钥 () 是必需的 API，如果没有这些 API，初始化将失败。
虽然 consistencyLevel 不是必需的，但我们强烈建议在生成客户端时注意此 API。 默认情况下，如果未提供帐户一致性级别，则使用帐户一致性级别。
默认情况下，如果未指定直接连接模式，则使用直接连接模式。
Building Cosmos Async Client minimal APIs (without any customized configurations)
CosmosAsyncClient client = new CosmosClientBuilder()
.endpoint(serviceEndpoint)
.key(key)
.buildAsyncClient();
Building Cosmos Async Client with customizations
CosmosAsyncClient client = new CosmosClientBuilder()
.endpoint(serviceEndpoint)
.key(key)
.directMode(directConnectionConfig, gatewayConnectionConfig)
.consistencyLevel(ConsistencyLevel.SESSION)
.connectionSharingAcrossClientsEnabled(true)
.contentResponseOnWriteEnabled(true)
.userAgentSuffix("my-application1-client")
.preferredRegions(Collections.singletonList("West US", "East US"))
.buildAsyncClient();
Building Cosmos Sync Client minimal APIs (without any customized configurations)
CosmosClient client = new CosmosClientBuilder()
.endpoint(serviceEndpoint)
.key(key)
.buildClient();
Building Cosmos Sync Client with customizations
CosmosClient client = new CosmosClientBuilder()
.endpoint(serviceEndpoint)
.key(key)
.directMode(directConnectionConfig, gatewayConnectionConfig)
.consistencyLevel(ConsistencyLevel.SESSION)
.connectionSharingAcrossClientsEnabled(true)
.contentResponseOnWriteEnabled(true)
.userAgentSuffix("my-application1-client")
.preferredRegions(Collections.singletonList("West US", "East US"))
.buildClient();
构造函数摘要
| 构造函数 | 说明 |
|---|---|
| CosmosClientBuilder() |
实例化新的 Cosmos 客户端生成器。 |
方法摘要
方法继承自 java.lang.Object
构造函数详细信息
CosmosClientBuilder
public CosmosClientBuilder()
实例化新的 Cosmos 客户端生成器。
方法详细信息
authorizationTokenResolver
public CosmosClientBuilder authorizationTokenResolver(CosmosAuthorizationTokenResolver cosmosAuthorizationTokenResolver)
设置令牌解析程序
Parameters:
Returns:
buildAsyncClient
public CosmosAsyncClient buildAsyncClient()
使用提供的属性生成 cosmos 异步客户端
Returns:
buildClient
public CosmosClient buildClient()
使用提供的属性生成 cosmos 同步客户端
Returns:
clientTelemetryConfig
public CosmosClientBuilder clientTelemetryConfig(CosmosClientTelemetryConfig telemetryConfig)
返回此生成器的客户端遥测配置实例
Parameters:
Returns:
clientTelemetryEnabled
public CosmosClientBuilder clientTelemetryEnabled(boolean clientTelemetryEnabled)
设置 标志以启用客户端遥测，这将定期收集数据库操作聚合统计信息、系统信息（如 cpu/内存），并将其发送到 cosmos 监视服务，这将在调试期间非常有用。
默认值为 false，表示这是选择加入功能，默认情况下不收集遥测数据。
Parameters:
Returns:
connectionSharingAcrossClientsEnabled
public CosmosClientBuilder connectionSharingAcrossClientsEnabled(boolean connectionSharingAcrossClientsEnabled)
启用跨多个 Cosmos 客户端共享的连接。 默认值为 false。
CosmosAsyncClient client1 = new CosmosClientBuilder()
.endpoint(serviceEndpoint1)
.key(key1)
.consistencyLevel(ConsistencyLevel.SESSION)
.connectionSharingAcrossClientsEnabled(true)
.buildAsyncClient();
CosmosAsyncClient client2 = new CosmosClientBuilder()
.endpoint(serviceEndpoint2)
.key(key2)
.consistencyLevel(ConsistencyLevel.SESSION)
.connectionSharingAcrossClientsEnabled(true)
.buildAsyncClient();
// when configured this way client1 and client2 will share connections when possible.
如果同一个 JVM 中有多个 Cosmos 客户端实例与多个 Cosmos 帐户交互，则启用此选项后可在 Cosmos 客户端的实例之间以直接模式进行连接共享（若可行）。 请注意，设置此选项时，将对其他所有客户端实例使用第一个实例化客户端的连接配置（例如套接字超时配置、空闲超时配置）。
Parameters:
Returns:
consistencyLevel
public CosmosClientBuilder consistencyLevel(ConsistencyLevel desiredConsistencyLevel)
ConsistencyLevel设置要使用的 默认情况下，SESSION将使用一致性。
Parameters:
Returns:
contentResponseOnWriteEnabled
public CosmosClientBuilder contentResponseOnWriteEnabled(boolean contentResponseOnWriteEnabled)
将布尔值设置为仅返回 Cosmos DB 响应中的标头和状态代码，以防对 CosmosItem 执行创建、更新和删除操作。 如果设置为 false (默认) ，则服务不会在响应中返回有效负载。 它通过不通过网络发送有效负载并在客户端上序列化有效负载来减少网络和 CPU 负载。 此功能不会影响读取或写入操作的 RU 使用情况。 默认情况下，这是 false。
Parameters:
Returns:
credential
public CosmosClientBuilder credential(AzureKeyCredential credential)
AzureKeyCredential设置要使用的
Parameters:
Returns:
credential
public CosmosClientBuilder credential(TokenCredential credential)
TokenCredential设置用于授权发送到服务的请求的 。 有关正确使用TokenCredential该类型的更多详细信息，请参阅适用于 Java 的 Azure SDK 标识和身份验证文档。
Parameters:
Returns:
directMode
public CosmosClientBuilder directMode()
设置要使用的默认 DIRECT 连接配置。 默认情况下，使用 directMode () 初始化生成器
Returns:
directMode
public CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig)
设置要使用的 DIRECT 连接配置。 默认情况下，使用 directMode () 初始化生成器
Parameters:
Returns:
directMode
public CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig, GatewayConnectionConfig gatewayConnectionConfig)
设置要使用的 DIRECT 连接配置。 gatewayConnectionConfig - 表示要用于网关客户端的基本配置。 即使在直接连接模式下，某些元数据操作也会通过网关客户端进行，在此 API 中设置网关连接配置不会影响连接模式，在本例中为直接连接模式。
Parameters:
Returns:
endToEndOperationLatencyPolicyConfig
public CosmosClientBuilder endToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig cosmosEndToEndOperationLatencyPolicyConfig)
CosmosEndToEndOperationLatencyPolicyConfig在客户端上设置
Parameters:
Returns:
endpoint
public CosmosClientBuilder endpoint(String endpoint)
设置 SDK 将连接到的 Azure Cosmos DB 终结点
Parameters:
Returns:
endpointDiscoveryEnabled
public CosmosClientBuilder endpointDiscoveryEnabled(boolean endpointDiscoveryEnabled)
设置 标志以启用异地复制数据库帐户的终结点发现。
如果 EnableEndpointDiscovery 为 true，SDK 将自动发现当前的写入和读取区域，以确保根据区域的功能和用户的首选项将请求发送到正确的区域。
此属性的默认值为 true，表示已启用终结点发现。
Parameters:
Returns:
excludedRegionsSupplier
public CosmosClientBuilder excludedRegionsSupplier(Supplier
设置在Supplier
Parameters:
CosmosExcludedRegions 供应商。
Returns:
gatewayMode
public CosmosClientBuilder gatewayMode()
设置要使用的默认网关连接配置。
Returns:
gatewayMode
public CosmosClientBuilder gatewayMode(GatewayConnectionConfig gatewayConnectionConfig)
设置要使用的网关连接配置。
Parameters:
Returns:
key
public CosmosClientBuilder key(String key)
设置用于执行访问资源的身份验证的主密钥或只读密钥。
Parameters:
Returns:
multipleWriteRegionsEnabled
public CosmosClientBuilder multipleWriteRegionsEnabled(boolean multipleWriteRegionsEnabled)
设置 标志以在 Azure Cosmos DB 服务中为异地复制的数据库帐户启用任何区域的写入。
当此属性的值为 true 时，SDK 会将写入操作定向到异地复制数据库帐户的可用可写区域。 可写区域按 PreferredRegions 属性排序。 在 DatabaseAccount 中的 EnableMultipleWriteRegions 也设置为 true 之前，将属性值设置为 true 不起作用。
默认值为 true，表示写入将定向到异地复制数据库帐户的可用可写区域。
Parameters:
Returns:
openConnectionsAndInitCaches
public CosmosClientBuilder openConnectionsAndInitCaches(CosmosContainerProactiveInitConfig proactiveContainerInitConfig)
设置 ， CosmosContainerProactiveInitConfig 它启用与从 getCosmosContainerIdentities() 获取的容器关联的缓存和连接预热到从第一 k 个首选区域获取的副本，其中 k 的计算结果为 getProactiveConnectionRegionsCount()。
CosmosContainerProactiveInitConfigBuilder使用 类实例化CosmosContainerProactiveInitConfig类
Parameters:
Returns:
permissions
public CosmosClientBuilder permissions(List
设置权限列表，其中包含访问资源所需的资源令牌。
Parameters:
Returns:
preferredRegions
public CosmosClientBuilder preferredRegions(List
设置异地复制数据库帐户的首选区域。 例如，“美国东部”作为首选区域。
当 EnableEndpointDiscovery 为 true 且 PreferredRegions 为非空时，SDK 将倾向于按照指定区域执行操作的顺序使用容器中的区域。
如果 EnableEndpointDiscovery 设置为 false，则忽略此属性。
Parameters:
Returns:
readRequestsFallbackEnabled
public CosmosClientBuilder readRequestsFallbackEnabled(boolean readRequestsFallbackEnabled)
设置是否允许读取转到在 Azure Cosmos DB 服务帐户上配置的多个区域。
默认值为 true。
如果未设置此属性，则对于除有限过期性之外的所有一致性级别，默认值为 true;对于有限过期，默认值为 false。 1. #endpointDiscoveryEnabled 为 true 2。 Azure Cosmos DB 帐户具有多个区域
Parameters:
Returns:
resourceToken
public CosmosClientBuilder resourceToken(String resourceToken)
设置用于执行访问资源的身份验证的资源令牌。
Parameters:
Returns:
sessionCapturingOverrideEnabled
public CosmosClientBuilder sessionCapturingOverrideEnabled(boolean sessionCapturingOverrideEnabled)
默认情况下为 SESSION启用会话捕获。 对于其他一致性级别，不需要，除非在会话中未配置客户端时偶尔发送具有会话一致性的请求。
为会话模式启用会话捕获不起作用。
Parameters:
Returns:
sessionRetryOptions
public CosmosClientBuilder sessionRetryOptions(SessionRetryOptions sessionRetryOptions)
在 SessionRetryOptions 客户端上设置实例。
此设置有助于优化与 NOT_FOUND / READ_SESSION_NOT_AVAILABLE 或 404 / 1002 关联的重试行为，当请求使用的目标一致性为 会话一致性 ，并且请求将转到请求查找的没有足够的最新数据的区域时发生。
免责声明：设置 SessionRetryOptions 将修改通过此客户端实例执行的所有操作或工作负载的重试行为。
对于多写入帐户：
- 对于转到本地读取区域的读取请求，可以通过在其他写入区域重试请求来优化可用性，因为其他写入区域可能具有更多最新的数据。
- 对于转到本地写入区域的读取请求，如果本地写入区域没有最新的数据，则立即切换到其他写入区域可能会有所帮助。
- 对于转到本地写入区域的写入请求，如果本地写入区域没有最新的数据，则立即切换到其他写入区域可能会有所帮助。
对于单写入帐户：
- 如果读取请求转到本地读取区域，则有助于更快地切换到写入区域。
- 如果读取请求转到写入区域，则 SessionRetryOptions 设置并不重要，因为单一写入帐户中的写入区域具有最新的数据。
- 对于单写入帐户中的写入区域，错误不适用，
READ_SESSION_NOT_AVAILABLE因为写入区域始终具有最新版本的数据，并且所有写入都转到此区域中的主要副本 (replica) 。 因此，此处不适用导致错误的复制滞后时间。
关于区域切换提示：
- 若要确定重试的本地区域的优先级，请使用提示 LOCAL_REGION_PREFERRED
- 为了更快地将重试移动到其他/远程区域，请使用提示 REMOTE_REGION_PREFERRED
支持的操作：
- 读取
- 查询
- 创建
- Replace
- Upsert
- 删除
- 修补程序
- Batch
- 批量
Parameters:
Returns:
throttlingRetryOptions
public CosmosClientBuilder throttlingRetryOptions(ThrottlingRetryOptions throttlingRetryOptions)
设置与 DocumentClient 实例关联的重试策略选项。
RetryOptions 类中的属性允许应用程序自定义内置的重试策略。 此属性是可选的。 如果未设置，SDK 将使用默认值来配置重试策略。 有关更多详细信息，请参阅 RetryOptions 类。
Parameters:
Returns:
userAgentSuffix
public CosmosClientBuilder userAgentSuffix(String userAgentSuffix)
设置用户代理后缀的值。
Parameters:
Returns:
适用于
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈