你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

CosmosClientBuilder 类

参考

包:: com.azure.cosmos

Maven 项目:: com.azure:azure-cosmos:4.58.0

java.lang.Object
- com.azure.cosmos.CosmosClientBuilder

实现

AzureKeyCredentialTrait<CosmosClientBuilder> EndpointTrait<CosmosClientBuilder> TokenCredentialTrait<CosmosClientBuilder>

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 客户端生成器。

方法摘要

修饰符和类型	方法和描述
CosmosClientBuilder	authorizationTokenResolver(CosmosAuthorizationTokenResolver cosmosAuthorizationTokenResolver) 设置令牌解析程序
CosmosAsyncClient	buildAsyncClient() 使用提供的属性生成 cosmos 异步客户端
CosmosClient	buildClient() 使用提供的属性生成 cosmos 同步客户端
CosmosClientBuilder	clientTelemetryConfig(CosmosClientTelemetryConfig telemetryConfig) 返回此生成器的客户端遥测配置实例
CosmosClientBuilder	clientTelemetryEnabled(boolean clientTelemetryEnabled) 设置标志以启用客户端遥测，这将定期收集数据库操作聚合统计信息、系统信息（如 cpu/内存），并将其发送到 cosmos 监视服务，这将在调试期间非常有用。
CosmosClientBuilder	connectionSharingAcrossClientsEnabled(boolean connectionSharingAcrossClientsEnabled) 启用跨多个 Cosmos 客户端共享连接。
CosmosClientBuilder	consistencyLevel(ConsistencyLevel desiredConsistencyLevel) ConsistencyLevel设置要使用的默认情况下，SESSION将使用一致性。
CosmosClientBuilder	contentResponseOnWriteEnabled(boolean contentResponseOnWriteEnabled) 将布尔值设置为仅返回 Cosmos DB 响应中的标头和状态代码，以防对 Cosmos项执行创建、更新和删除操作。
CosmosClientBuilder	credential(AzureKeyCredential credential) AzureKeyCredential设置要使用的
CosmosClientBuilder	credential(TokenCredential credential) TokenCredential设置用于授权发送到服务的请求的。
CosmosClientBuilder	directMode() 设置要使用的默认 DIRECT 连接配置。
CosmosClientBuilder	directMode(DirectConnectionConfig directConnectionConfig) 设置要使用的 DIRECT 连接配置。
CosmosClientBuilder	directMode(DirectConnectionConfig directConnectionConfig, GatewayConnectionConfig gatewayConnectionConfig) 设置要使用的 DIRECT 连接配置。
CosmosClientBuilder	endToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig cosmosEndToEndOperationLatencyPolicyConfig) CosmosEndToEndOperationLatencyPolicyConfig在客户端上设置
CosmosClientBuilder	endpoint(String endpoint) 设置 SDK 将连接到的 Azure Cosmos DB 终结点
CosmosClientBuilder	endpointDiscoveryEnabled(boolean endpointDiscoveryEnabled) 设置标志以启用异地复制数据库帐户的终结点发现。
CosmosClientBuilder	excludedRegionsSupplier(Supplier<CosmosExcludedRegions> excludedRegionsSupplier) 设置在Supplier调用时Supplier#get()返回实例的 CosmosExcludedRegions 。
CosmosClientBuilder	gatewayMode() 设置要使用的默认网关连接配置。
CosmosClientBuilder	gatewayMode(GatewayConnectionConfig gatewayConnectionConfig) 设置要使用的网关连接配置。
CosmosClientBuilder	key(String key) 设置用于执行访问资源的身份验证的主密钥或只读密钥。
CosmosClientBuilder	multipleWriteRegionsEnabled(boolean multipleWriteRegionsEnabled) 设置标志以在 Azure Cosmos DB 服务中为异地复制的数据库帐户启用任何区域的写入。
CosmosClientBuilder	openConnectionsAndInitCaches(CosmosContainerProactiveInitConfig proactiveContainerInitConfig) 设置， CosmosContainerProactiveInitConfig 它启用与从 getCosmosContainerIdentities() 获取的容器关联的缓存和连接预热到从第一 k 个首选区域获取的副本，其中 k 的计算结果为 getProactiveConnectionRegionsCount()。
CosmosClientBuilder	permissions(List<CosmosPermissionProperties> permissions) 设置权限列表，其中包含访问资源所需的资源令牌。
CosmosClientBuilder	preferredRegions(List<String> preferredRegions) 设置异地复制数据库帐户的首选区域。
CosmosClientBuilder	readRequestsFallbackEnabled(boolean readRequestsFallbackEnabled) 设置是否允许读取转到在 Azure Cosmos DB 服务帐户上配置的多个区域。
CosmosClientBuilder	resourceToken(String resourceToken) 设置用于执行访问资源的身份验证的资源令牌。
CosmosClientBuilder	sessionCapturingOverrideEnabled(boolean sessionCapturingOverrideEnabled) 默认情况下为 SESSION启用会话捕获。
CosmosClientBuilder	sessionRetryOptions(SessionRetryOptions sessionRetryOptions) 在 SessionRetryOptions 客户端上设置实例。
CosmosClientBuilder	throttlingRetryOptions(ThrottlingRetryOptions throttlingRetryOptions) 设置与文档客户端实例关联的重试策略选项。
CosmosClientBuilder	userAgentSuffix(String userAgentSuffix) 设置用户代理后缀的值。

方法继承自 java.lang.Object

clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

构造函数详细信息

CosmosClientBuilder

public CosmosClientBuilder()

实例化新的 Cosmos 客户端生成器。

方法详细信息

authorizationTokenResolver

public CosmosClientBuilder authorizationTokenResolver(CosmosAuthorizationTokenResolver cosmosAuthorizationTokenResolver)

设置令牌解析程序

Parameters:

cosmosAuthorizationTokenResolver - 令牌解析程序

Returns:

当前 cosmosClientBuilder

buildAsyncClient

public CosmosAsyncClient buildAsyncClient()

使用提供的属性生成 cosmos 异步客户端

Returns:

CosmosAsyncClient

buildClient

public CosmosClient buildClient()

使用提供的属性生成 cosmos 同步客户端

Returns:

CosmosClient

clientTelemetryConfig

public CosmosClientBuilder clientTelemetryConfig(CosmosClientTelemetryConfig telemetryConfig)

返回此生成器的客户端遥测配置实例

Parameters:

telemetryConfig - 要使用的客户端遥测配置

Returns:

当前 CosmosClientBuilder

clientTelemetryEnabled

public CosmosClientBuilder clientTelemetryEnabled(boolean clientTelemetryEnabled)

设置标志以启用客户端遥测，这将定期收集数据库操作聚合统计信息、系统信息（如 cpu/内存），并将其发送到 cosmos 监视服务，这将在调试期间非常有用。

默认值为 false，表示这是选择加入功能，默认情况下不收集遥测数据。

Parameters:

clientTelemetryEnabled - 用于启用客户端遥测的标志。

Returns:

当前 CosmosClientBuilder

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:

connectionSharingAcrossClientsEnabled - 连接共享

Returns:

current cosmosClientBuilder

consistencyLevel

public CosmosClientBuilder consistencyLevel(ConsistencyLevel desiredConsistencyLevel)

ConsistencyLevel设置要使用的默认情况下，SESSION将使用一致性。

Parameters:

desiredConsistencyLevel - ConsistencyLevel

Returns:

当前生成器

contentResponseOnWriteEnabled

public CosmosClientBuilder contentResponseOnWriteEnabled(boolean contentResponseOnWriteEnabled)

将布尔值设置为仅返回 Cosmos DB 响应中的标头和状态代码，以防对 CosmosItem 执行创建、更新和删除操作。如果设置为 false (默认) ，则服务不会在响应中返回有效负载。它通过不通过网络发送有效负载并在客户端上序列化有效负载来减少网络和 CPU 负载。此功能不会影响读取或写入操作的 RU 使用情况。默认情况下，这是 false。

Parameters:

contentResponseOnWriteEnabled - 一个布尔值，指示是否将在响应中包含有效负载

Returns:

current cosmosClientBuilder

credential

public CosmosClientBuilder credential(AzureKeyCredential credential)

AzureKeyCredential设置要使用的

Parameters:

credential - AzureKeyCredential

Returns:

current cosmosClientBuilder

credential

public CosmosClientBuilder credential(TokenCredential credential)

TokenCredential设置用于授权发送到服务的请求的。有关正确使用TokenCredential该类型的更多详细信息，请参阅适用于 Java 的 Azure SDK 标识和身份验证文档。

Parameters:

credential - TokenCredential 用于授权发送到服务的请求。

Returns:

更新的 CosmosClientBuilder

directMode

public CosmosClientBuilder directMode()

设置要使用的默认 DIRECT 连接配置。默认情况下，使用 directMode () 初始化生成器

Returns:

当前 CosmosClientBuilder

directMode

public CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig)

设置要使用的 DIRECT 连接配置。默认情况下，使用 directMode () 初始化生成器

Parameters:

directConnectionConfig - 直接连接配置

Returns:

当前 CosmosClientBuilder

directMode

public CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig, GatewayConnectionConfig gatewayConnectionConfig)

设置要使用的 DIRECT 连接配置。 gatewayConnectionConfig - 表示要用于网关客户端的基本配置。即使在直接连接模式下，某些元数据操作也会通过网关客户端进行，在此 API 中设置网关连接配置不会影响连接模式，在本例中为直接连接模式。

Parameters:

directConnectionConfig - 要使用的直接连接配置

gatewayConnectionConfig - 要使用的网关连接配置

Returns:

当前 CosmosClientBuilder

endToEndOperationLatencyPolicyConfig

public CosmosClientBuilder endToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig cosmosEndToEndOperationLatencyPolicyConfig)

CosmosEndToEndOperationLatencyPolicyConfig在客户端上设置

Parameters:

cosmosEndToEndOperationLatencyPolicyConfig - CosmosEndToEndOperationLatencyPolicyConfig

Returns:

当前 CosmosClientBuilder

endpoint

public CosmosClientBuilder endpoint(String endpoint)

设置 SDK 将连接到的 Azure Cosmos DB 终结点

Parameters:

endpoint - 服务终结点

Returns:

当前生成器

endpointDiscoveryEnabled

public CosmosClientBuilder endpointDiscoveryEnabled(boolean endpointDiscoveryEnabled)

设置标志以启用异地复制数据库帐户的终结点发现。

如果 EnableEndpointDiscovery 为 true，SDK 将自动发现当前的写入和读取区域，以确保根据区域的功能和用户的首选项将请求发送到正确的区域。

此属性的默认值为 true，表示已启用终结点发现。

Parameters:

endpointDiscoveryEnabled - 如果已启用 EndpointDiscovery，则为 true。

Returns:

当前 CosmosClientBuilder

excludedRegionsSupplier

public CosmosClientBuilder excludedRegionsSupplier(Supplier excludedRegionsSupplier)

设置在Supplier调用时Supplier#get()返回实例的 CosmosExcludedRegions 。对于通过此实例CosmosClient / CosmosAsyncClient执行的工作负载，请求不会路由到中getExcludedRegions()存在的区域，用于对冲方案和重试方案。

Parameters:

excludedRegionsSupplier - 返回实例的 CosmosExcludedRegions 供应商。

Returns:

当前 CosmosClientBuilder。

gatewayMode

public CosmosClientBuilder gatewayMode()

设置要使用的默认网关连接配置。

Returns:

当前 CosmosClientBuilder

gatewayMode

public CosmosClientBuilder gatewayMode(GatewayConnectionConfig gatewayConnectionConfig)

设置要使用的网关连接配置。

Parameters:

gatewayConnectionConfig - 网关连接配置

Returns:

当前 CosmosClientBuilder

key

public CosmosClientBuilder key(String key)

设置用于执行访问资源的身份验证的主密钥或只读密钥。

Parameters:

key - master 或 readonly 密钥

Returns:

当前生成器。

multipleWriteRegionsEnabled

public CosmosClientBuilder multipleWriteRegionsEnabled(boolean multipleWriteRegionsEnabled)

设置标志以在 Azure Cosmos DB 服务中为异地复制的数据库帐户启用任何区域的写入。

当此属性的值为 true 时，SDK 会将写入操作定向到异地复制数据库帐户的可用可写区域。可写区域按 PreferredRegions 属性排序。在 DatabaseAccount 中的 EnableMultipleWriteRegions 也设置为 true 之前，将属性值设置为 true 不起作用。

默认值为 true，表示写入将定向到异地复制数据库帐户的可用可写区域。

Parameters:

multipleWriteRegionsEnabled - 标志用于在异地复制数据库帐户的任何区域中启用写入。

Returns:

当前 CosmosClientBuilder

openConnectionsAndInitCaches

public CosmosClientBuilder openConnectionsAndInitCaches(CosmosContainerProactiveInitConfig proactiveContainerInitConfig)

设置， CosmosContainerProactiveInitConfig 它启用与从 getCosmosContainerIdentities() 获取的容器关联的缓存和连接预热到从第一 k 个首选区域获取的副本，其中 k 的计算结果为 getProactiveConnectionRegionsCount()。

CosmosContainerProactiveInitConfigBuilder使用类实例化CosmosContainerProactiveInitConfig类

Parameters:

proactiveContainerInitConfig - 它封装了容器标识列表，没有主动连接区域

Returns:

当前 CosmosClientBuilder

permissions

public CosmosClientBuilder permissions(List permissions)

设置权限列表，其中包含访问资源所需的资源令牌。

Parameters:

permissions - 身份验证的权限列表。

Returns:

当前生成器。

preferredRegions

public CosmosClientBuilder preferredRegions(List preferredRegions)

设置异地复制数据库帐户的首选区域。例如，“美国东部”作为首选区域。

当 EnableEndpointDiscovery 为 true 且 PreferredRegions 为非空时，SDK 将倾向于按照指定区域执行操作的顺序使用容器中的区域。

如果 EnableEndpointDiscovery 设置为 false，则忽略此属性。

Parameters:

preferredRegions - 首选区域的列表。

Returns:

当前 CosmosClientBuilder

readRequestsFallbackEnabled

public CosmosClientBuilder readRequestsFallbackEnabled(boolean readRequestsFallbackEnabled)

设置是否允许读取转到在 Azure Cosmos DB 服务帐户上配置的多个区域。

默认值为 true。

如果未设置此属性，则对于除有限过期性之外的所有一致性级别，默认值为 true;对于有限过期，默认值为 false。 1. #endpointDiscoveryEnabled 为 true 2。 Azure Cosmos DB 帐户具有多个区域

Parameters:

readRequestsFallbackEnabled - 标志用于启用读取以转到在 Azure Cosmos DB 服务帐户上配置的多个区域。

Returns:

当前 CosmosClientBuilder

resourceToken

public CosmosClientBuilder resourceToken(String resourceToken)

设置用于执行访问资源的身份验证的资源令牌。

Parameters:

resourceToken - 用于身份验证的 resourceToken

Returns:

当前生成器。

sessionCapturingOverrideEnabled

public CosmosClientBuilder sessionCapturingOverrideEnabled(boolean sessionCapturingOverrideEnabled)

默认情况下为 SESSION启用会话捕获。对于其他一致性级别，不需要，除非在会话中未配置客户端时偶尔发送具有会话一致性的请求。

为会话模式启用会话捕获不起作用。

Parameters:

sessionCapturingOverrideEnabled - 会话捕获替代

Returns:

current cosmosClientBuilder

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:

sessionRetryOptions - SessionRetryOptions 实例。

Returns:

当前 CosmosClientBuilder

throttlingRetryOptions

public CosmosClientBuilder throttlingRetryOptions(ThrottlingRetryOptions throttlingRetryOptions)

设置与 DocumentClient 实例关联的重试策略选项。

RetryOptions 类中的属性允许应用程序自定义内置的重试策略。此属性是可选的。如果未设置，SDK 将使用默认值来配置重试策略。有关更多详细信息，请参阅 RetryOptions 类。

Parameters:

throttlingRetryOptions - RetryOptions 实例。

Returns:

当前 CosmosClientBuilder

userAgentSuffix

public CosmosClientBuilder userAgentSuffix(String userAgentSuffix)

设置用户代理后缀的值。

Parameters:

userAgentSuffix - 要追加到 user-agent 标头的值，用于监视目的。

Returns:

当前 CosmosClientBuilder

通过

CosmosClientBuilder 类

构造函数摘要

方法摘要

方法继承自 java.lang.Object

构造函数详细信息

CosmosClientBuilder

方法详细信息

authorizationTokenResolver

buildAsyncClient

buildClient

clientTelemetryConfig

clientTelemetryEnabled

connectionSharingAcrossClientsEnabled

consistencyLevel

contentResponseOnWriteEnabled

credential

credential

directMode

directMode

directMode

endToEndOperationLatencyPolicyConfig

endpoint

endpointDiscoveryEnabled

excludedRegionsSupplier

gatewayMode

gatewayMode

key

multipleWriteRegionsEnabled

openConnectionsAndInitCaches

permissions

preferredRegions

readRequestsFallbackEnabled

resourceToken

sessionCapturingOverrideEnabled

sessionRetryOptions

throttlingRetryOptions

userAgentSuffix

适用于

其他资源