Compartilhar via


CosmosClientBuilder Classe

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

Implementações

public class CosmosClientBuilder
implements TokenCredentialTrait<CosmosClientBuilder>, AzureKeyCredentialTrait<CosmosClientBuilder>, EndpointTrait<CosmosClientBuilder>

Classe auxiliar para compilar CosmosAsyncClient e CosmosClient instâncias como representação lógica do serviço de banco de dados do Azure Cosmos.

CosmosAsyncClient e CosmosClient são thread-safe. É recomendável manter uma única instância de CosmosClient ou CosmosAsyncClient por tempo de vida do aplicativo, o que permite o gerenciamento e o desempenho de conexões eficientes. As inicializações do CosmosAsyncClient e do CosmosClient são operações pesadas– não use as instâncias de inicialização CosmosAsyncClient ou CosmosClient como credenciais ou validações de conectividade de rede.

Ao criar o cliente, endpoint() e key() são APIs obrigatórias, sem elas a inicialização falhará.

Embora consistencyLevel não seja obrigatório, mas é altamente recomendável prestar atenção a essa API ao criar o cliente. Por padrão, o nível de consistência da conta será usado se nenhum for fornecido.

Por padrão, o modo de conexão direta será usado se nenhum especificado.

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();

Resumo do Construtor

Construtor Description
CosmosClientBuilder()

Cria uma instância de um novo construtor de clientes do Cosmos.

Resumo do método

Modificador e tipo Método e descrição
CosmosClientBuilder authorizationTokenResolver(CosmosAuthorizationTokenResolver cosmosAuthorizationTokenResolver)

Define o resolvedor de token

CosmosAsyncClient buildAsyncClient()

Cria um cliente assíncrono do Cosmos com as propriedades fornecidas

CosmosClient buildClient()

Cria um cliente de sincronização do Cosmos com as propriedades fornecidas

CosmosClientBuilder clientTelemetryConfig(CosmosClientTelemetryConfig telemetryConfig)

Retorna a instância de configuração de telemetria do cliente para este construtor

CosmosClientBuilder clientTelemetryEnabled(boolean clientTelemetryEnabled)

Define o sinalizador para habilitar a telemetria do cliente, que coletará periodicamente estatísticas de agregação de operações de banco de dados, informações do sistema como cpu/memória e as enviará para o serviço de monitoramento do Cosmos, o que será útil durante a depuração.

CosmosClientBuilder connectionSharingAcrossClientsEnabled(boolean connectionSharingAcrossClientsEnabled)

Habilita o compartilhamento de conexões em vários clientes do Cosmos.

CosmosClientBuilder consistencyLevel(ConsistencyLevel desiredConsistencyLevel)

Define o ConsistencyLevel a ser usado Por padrão, SESSION a consistência será usada.

CosmosClientBuilder contentResponseOnWriteEnabled(boolean contentResponseOnWriteEnabled)

Define o booliano para retornar apenas os cabeçalhos e status código na resposta do Cosmos DB no caso das operações Criar, Atualizar e Excluir no Item do Cosmos.

CosmosClientBuilder credential(AzureKeyCredential credential)

Define o AzureKeyCredential a ser usado

CosmosClientBuilder credential(TokenCredential credential)

Define o TokenCredential usado para autorizar solicitações enviadas ao serviço.

CosmosClientBuilder directMode()

Define a configuração de conexão DIRECT padrão a ser usada.

CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig)

Define a configuração de conexão DIRECT a ser usada.

CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig, GatewayConnectionConfig gatewayConnectionConfig)

Define a configuração de conexão DIRECT a ser usada.

CosmosClientBuilder endToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig cosmosEndToEndOperationLatencyPolicyConfig)

Define o CosmosEndToEndOperationLatencyPolicyConfig no cliente

CosmosClientBuilder endpoint(String endpoint)

Define o ponto de extremidade do Azure Cosmos DB ao qual o SDK se conectará

CosmosClientBuilder endpointDiscoveryEnabled(boolean endpointDiscoveryEnabled)

Define o sinalizador para habilitar a descoberta de ponto de extremidade para contas de banco de dados replicadas geograficamente.

CosmosClientBuilder excludedRegionsSupplier(Supplier<CosmosExcludedRegions> excludedRegionsSupplier)

Define um Supplier que retorna uma CosmosExcludedRegions instância quando Supplier#get() é invocado.

CosmosClientBuilder gatewayMode()

Define a configuração de conexão GATEWAY padrão a ser usada.

CosmosClientBuilder gatewayMode(GatewayConnectionConfig gatewayConnectionConfig)

Define a configuração de conexão GATEWAY a ser usada.

CosmosClientBuilder key(String key)

Define uma chave master ou somente leitura usada para executar a autenticação para acessar o recurso.

CosmosClientBuilder multipleWriteRegionsEnabled(boolean multipleWriteRegionsEnabled)

Define o sinalizador para habilitar gravações em qualquer região para contas de banco de dados replicadas geograficamente no serviço do Azure Cosmos DB.

CosmosClientBuilder openConnectionsAndInitCaches(CosmosContainerProactiveInitConfig proactiveContainerInitConfig)

Define o que permite o CosmosContainerProactiveInitConfig aquecimento de caches e conexões associadas a contêineres obtidos de getCosmosContainerIdentities() para réplicas obtidas das primeiras k regiões preferenciais em que k é avaliado como getProactiveConnectionRegionsCount().

CosmosClientBuilder permissions(List<CosmosPermissionProperties> permissions)

Define a lista de permissões, que contém os tokens de recurso necessários para acessar recursos.

CosmosClientBuilder preferredRegions(List<String> preferredRegions)

Define as regiões preferenciais para contas de banco de dados replicadas geograficamente.

CosmosClientBuilder readRequestsFallbackEnabled(boolean readRequestsFallbackEnabled)

Define se as leituras devem ser permitidas para ir para várias regiões configuradas em uma conta do serviço do Azure Cosmos DB.

CosmosClientBuilder resourceToken(String resourceToken)

Define um token de recurso usado para executar a autenticação para acessar o recurso.

CosmosClientBuilder sessionCapturingOverrideEnabled(boolean sessionCapturingOverrideEnabled)

A captura de sessão está habilitada por padrão para SESSION.

CosmosClientBuilder sessionRetryOptions(SessionRetryOptions sessionRetryOptions)

Define a SessionRetryOptions instância no cliente.

CosmosClientBuilder throttlingRetryOptions(ThrottlingRetryOptions throttlingRetryOptions)

Define as opções de política de repetição associadas à instância do Cliente de Documento.

CosmosClientBuilder userAgentSuffix(String userAgentSuffix)

define o valor do sufixo user-agent.

Métodos herdados de java.lang.Object

Detalhes do construtor

CosmosClientBuilder

public CosmosClientBuilder()

Cria uma instância de um novo construtor de clientes do Cosmos.

Detalhes do método

authorizationTokenResolver

public CosmosClientBuilder authorizationTokenResolver(CosmosAuthorizationTokenResolver cosmosAuthorizationTokenResolver)

Define o resolvedor de token

Parameters:

cosmosAuthorizationTokenResolver - o resolvedor de token

Returns:

cosmosClientBuilder atual

buildAsyncClient

public CosmosAsyncClient buildAsyncClient()

Cria um cliente assíncrono do Cosmos com as propriedades fornecidas

Returns:

CosmosAsyncClient

buildClient

public CosmosClient buildClient()

Cria um cliente de sincronização do Cosmos com as propriedades fornecidas

Returns:

CosmosClient

clientTelemetryConfig

public CosmosClientBuilder clientTelemetryConfig(CosmosClientTelemetryConfig telemetryConfig)

Retorna a instância de configuração de telemetria do cliente para este construtor

Parameters:

telemetryConfig - a configuração de telemetria do cliente a ser usada

Returns:

CosmosClientBuilder atual

clientTelemetryEnabled

public CosmosClientBuilder clientTelemetryEnabled(boolean clientTelemetryEnabled)

Define o sinalizador para habilitar a telemetria do cliente, que coletará periodicamente estatísticas de agregação de operações de banco de dados, informações do sistema como cpu/memória e as enviará para o serviço de monitoramento do Cosmos, o que será útil durante a depuração.

O valor DEFAULT é false, indicando que isso é aceita no recurso, por padrão, nenhuma coleção de telemetria.

Parameters:

clientTelemetryEnabled - sinalizador para habilitar a telemetria do cliente.

Returns:

CosmosClientBuilder atual

connectionSharingAcrossClientsEnabled

public CosmosClientBuilder connectionSharingAcrossClientsEnabled(boolean connectionSharingAcrossClientsEnabled)

Habilita o compartilhamento de conexões em vários clientes do Cosmos. O padrão é 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.

Quando você tem várias instâncias do cliente do Cosmos na mesma JVM interagindo com várias contas do Cosmos, habilitar isso permite o compartilhamento de conexão no modo direto, se possível, entre instâncias de cliente do Cosmos. Observe que, ao definir essa opção, a configuração da conexão (por exemplo, configuração de tempo limite do soquete, configuração de tempo limite ocioso) do primeiro cliente instanciado será usada para todas as outras instâncias de cliente.

Parameters:

connectionSharingAcrossClientsEnabled - compartilhamento de conexão

Returns:

cosmosClientBuilder atual

consistencyLevel

public CosmosClientBuilder consistencyLevel(ConsistencyLevel desiredConsistencyLevel)

Define o ConsistencyLevel a ser usado Por padrão, SESSION a consistência será usada.

Parameters:

desiredConsistencyLevel - ConsistencyLevel

Returns:

Construtor atual

contentResponseOnWriteEnabled

public CosmosClientBuilder contentResponseOnWriteEnabled(boolean contentResponseOnWriteEnabled)

Define o booliano para retornar apenas os cabeçalhos e status código na resposta do Cosmos DB no caso das operações Criar, Atualizar e Excluir no CosmosItem. Se definido como false (o que é por padrão), o serviço não retorna a carga na resposta. Ele reduz a rede e a carga da CPU, não enviando a carga de volta pela rede e serializando-a no cliente. Esse recurso não afeta o uso de RU para operações de leitura ou gravação. Por padrão, isso é falso.

Parameters:

contentResponseOnWriteEnabled - um booliano que indica se a carga será incluída na resposta ou não

Returns:

cosmosClientBuilder atual

credential

public CosmosClientBuilder credential(AzureKeyCredential credential)

Define o AzureKeyCredential a ser usado

Parameters:

credential - AzureKeyCredential

Returns:

cosmosClientBuilder atual

credential

public CosmosClientBuilder credential(TokenCredential credential)

Define o TokenCredential usado para autorizar solicitações enviadas ao serviço. Consulte a documentação de identidade e autenticação do SDK do Azure para Java para obter mais detalhes sobre o uso adequado do TokenCredential tipo.

Parameters:

credential - TokenCredential usado para autorizar solicitações enviadas ao serviço.

Returns:

o CosmosClientBuilder atualizado

directMode

public CosmosClientBuilder directMode()

Define a configuração de conexão DIRECT padrão a ser usada. Por padrão, o construtor é inicializado com directMode()

Returns:

CosmosClientBuilder atual

directMode

public CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig)

Define a configuração de conexão DIRECT a ser usada. Por padrão, o construtor é inicializado com directMode()

Parameters:

directConnectionConfig - configuração de conexão direta

Returns:

CosmosClientBuilder atual

directMode

public CosmosClientBuilder directMode(DirectConnectionConfig directConnectionConfig, GatewayConnectionConfig gatewayConnectionConfig)

Define a configuração de conexão DIRECT a ser usada. gatewayConnectionConfig – representa a configuração básica a ser usada para o cliente de gateway. Mesmo no modo de conexão direta, algumas das operações de metadados passam pelo cliente de gateway, a configuração da configuração de conexão de gateway nessa API não afeta o modo de conexão, que será Direct nesse caso.

Parameters:

directConnectionConfig - configuração de conexão direta a ser usada
gatewayConnectionConfig - configuração de conexão de gateway a ser usada

Returns:

CosmosClientBuilder atual

endToEndOperationLatencyPolicyConfig

public CosmosClientBuilder endToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig cosmosEndToEndOperationLatencyPolicyConfig)

Define o CosmosEndToEndOperationLatencyPolicyConfig no cliente

Parameters:

cosmosEndToEndOperationLatencyPolicyConfig - O CosmosEndToEndOperationLatencyPolicyConfig

Returns:

CosmosClientBuilder atual

endpoint

public CosmosClientBuilder endpoint(String endpoint)

Define o ponto de extremidade do Azure Cosmos DB ao qual o SDK se conectará

Parameters:

endpoint - o ponto de extremidade de serviço

Returns:

Construtor atual

endpointDiscoveryEnabled

public CosmosClientBuilder endpointDiscoveryEnabled(boolean endpointDiscoveryEnabled)

Define o sinalizador para habilitar a descoberta de ponto de extremidade para contas de banco de dados replicadas geograficamente.

Quando EnableEndpointDiscovery for true, o SDK descobrirá automaticamente as regiões de gravação e leitura atuais para garantir que as solicitações sejam enviadas para a região correta com base na capacidade da região e na preferência do usuário.

O valor padrão dessa propriedade é verdadeiro indicando que a descoberta de ponto de extremidade está habilitada.

Parameters:

endpointDiscoveryEnabled - true se EndpointDiscovery estiver habilitado.

Returns:

CosmosClientBuilder atual

excludedRegionsSupplier

public CosmosClientBuilder excludedRegionsSupplier(Supplier excludedRegionsSupplier)

Define um Supplier que retorna uma CosmosExcludedRegions instância quando Supplier#get() é invocado. A solicitação não será roteada para regiões presentes em getExcludedRegions() para cenários de cobertura e cenários de repetição para a carga de trabalho executada por meio dessa instância do / CosmosClientCosmosAsyncClient .

Parameters:

excludedRegionsSupplier - o fornecedor que retorna uma CosmosExcludedRegions instância.

Returns:

CosmosClientBuilder atual.

gatewayMode

public CosmosClientBuilder gatewayMode()

Define a configuração de conexão GATEWAY padrão a ser usada.

Returns:

CosmosClientBuilder atual

gatewayMode

public CosmosClientBuilder gatewayMode(GatewayConnectionConfig gatewayConnectionConfig)

Define a configuração de conexão GATEWAY a ser usada.

Parameters:

gatewayConnectionConfig - configuração de conexão de gateway

Returns:

CosmosClientBuilder atual

key

public CosmosClientBuilder key(String key)

Define uma chave master ou somente leitura usada para executar a autenticação para acessar o recurso.

Parameters:

key - master ou chave somente leitura

Returns:

Construtor atual.

multipleWriteRegionsEnabled

public CosmosClientBuilder multipleWriteRegionsEnabled(boolean multipleWriteRegionsEnabled)

Define o sinalizador para habilitar gravações em qualquer região para contas de banco de dados replicadas geograficamente no serviço do Azure Cosmos DB.

Quando o valor dessa propriedade for true, o SDK direcionará operações de gravação para regiões graváveis disponíveis da conta de banco de dados replicada geograficamente. As regiões graváveis são ordenadas pela propriedade PreferredRegions. Definir o valor da propriedade como true não terá efeito até EnableMultipleWriteRegions em DatabaseAccount também ser definido como true.

O valor DEFAULT é verdadeiro indicando que as gravações são direcionadas para regiões graváveis disponíveis da conta de banco de dados replicada geograficamente.

Parameters:

multipleWriteRegionsEnabled - sinalizador para habilitar gravações em todas as regiões para contas de banco de dados replicadas geograficamente.

Returns:

CosmosClientBuilder atual

openConnectionsAndInitCaches

public CosmosClientBuilder openConnectionsAndInitCaches(CosmosContainerProactiveInitConfig proactiveContainerInitConfig)

Define o que permite o CosmosContainerProactiveInitConfig aquecimento de caches e conexões associadas a contêineres obtidos de getCosmosContainerIdentities() para réplicas obtidas das primeiras k regiões preferenciais em que k é avaliado como getProactiveConnectionRegionsCount().

Usar a CosmosContainerProactiveInitConfigBuilder classe para instanciar a CosmosContainerProactiveInitConfig classe

Parameters:

proactiveContainerInitConfig - que encapsula uma lista de identidades de contêiner e nenhuma das regiões de conexão proativas

Returns:

CosmosClientBuilder atual

permissions

public CosmosClientBuilder permissions(List permissions)

Define a lista de permissões, que contém os tokens de recurso necessários para acessar recursos.

Parameters:

permissions - Lista de permissões para autenticação.

Returns:

Construtor atual.

preferredRegions

public CosmosClientBuilder preferredRegions(List preferredRegions)

Define as regiões preferenciais para contas de banco de dados replicadas geograficamente. Por exemplo, "Leste dos EUA" como a região preferencial.

Quando EnableEndpointDiscovery for true e PreferredRegions não estiver vazio, o SDK preferirá usar as regiões no contêiner na ordem em que forem especificadas para executar operações.

Se EnableEndpointDiscovery estiver definido como false, essa propriedade será ignorada.

Parameters:

preferredRegions - a lista de regiões preferenciais.

Returns:

CosmosClientBuilder atual

readRequestsFallbackEnabled

public CosmosClientBuilder readRequestsFallbackEnabled(boolean readRequestsFallbackEnabled)

Define se as leituras devem ser permitidas para ir para várias regiões configuradas em uma conta do serviço do Azure Cosmos DB.

O valor DEFAULT é true.

Se essa propriedade não estiver definida, o padrão será true para todos os Níveis de Consistência diferentes de Desatualização Limitada, o padrão será false para Desatualização Limitada. 1. #endpointDiscoveryEnabled é true 2. a conta do Azure Cosmos DB tem mais de uma região

Parameters:

readRequestsFallbackEnabled - sinalizador para habilitar leituras para ir para várias regiões configuradas em uma conta do serviço do Azure Cosmos DB.

Returns:

CosmosClientBuilder atual

resourceToken

public CosmosClientBuilder resourceToken(String resourceToken)

Define um token de recurso usado para executar a autenticação para acessar o recurso.

Parameters:

resourceToken - resourceToken para autenticação

Returns:

Construtor atual.

sessionCapturingOverrideEnabled

public CosmosClientBuilder sessionCapturingOverrideEnabled(boolean sessionCapturingOverrideEnabled)

A captura de sessão está habilitada por padrão para SESSION. Para outros níveis de consistência, ele não é necessário, a menos que você precise enviar solicitações ocasionalmente com Consistência de Sessão enquanto o cliente não estiver configurado na sessão.

habilitar a captura de sessão para o modo sessão não tem efeito.

Parameters:

sessionCapturingOverrideEnabled - substituição de captura de sessão

Returns:

cosmosClientBuilder atual

sessionRetryOptions

public CosmosClientBuilder sessionRetryOptions(SessionRetryOptions sessionRetryOptions)

Define a SessionRetryOptions instância no cliente.

Essa configuração ajuda a otimizar o comportamento de repetição associado NOT_FOUND / READ_SESSION_NOT_AVAILABLE a cenários ou 404 / 1002 que ocorrem quando a consistência de destino usada pela solicitação é Consistência de Sessão e uma solicitação vai para uma região que não tem dados recentes o suficiente que a solicitação está procurando.

ISENÇÃO DE RESPONSABILIDADE: a configuração SessionRetryOptions modificará o comportamento de repetição para todas as operações ou cargas de trabalho executadas por meio dessa instância do cliente.

Para contas de várias gravações:

  • Para uma solicitação de leitura que vai para uma região de leitura local, é possível otimizar a disponibilidade fazendo com que a solicitação seja repetida em uma região de gravação diferente, pois a outra região de gravação pode ter dados mais atualizados.
  • Para uma solicitação de leitura que vai para uma região de gravação local, isso pode ajudar a mudar para uma região de gravação diferente imediatamente, desde que a região de gravação local não tenha os dados mais atualizados.
  • Para uma solicitação de gravação que vai para uma região de gravação local, isso pode ajudar a alternar para uma região de gravação diferente imediatamente, desde que a região de gravação local não tenha os dados mais atualizados.

Para contas de gravação única:

  • Se uma solicitação de leitura for para uma região de leitura local, ela ajudará a alternar para a região de gravação mais rapidamente.
  • Se uma solicitação de leitura for para uma região de gravação, a SessionRetryOptions configuração não será importante, pois a região de gravação em uma conta de gravação única tem os dados mais atualizados.
  • Para uma gravação em uma região de gravação em uma conta de gravação única, os erros não se aplicam, READ_SESSION_NOT_AVAILABLE pois a região de gravação sempre tem a versão mais recente dos dados e todas as gravações vão para o réplica primário nessa região. Portanto, os atrasos de replicação que causam erros não são aplicáveis aqui.

Sobre dicas de alternância de região:

Operações com suporte:

  • Ler
  • Consulta
  • Criar
  • Substitua
  • Upsert
  • Excluir
  • Patch
  • Lote
  • Em massa

Parameters:

sessionRetryOptions - A instância SessionRetryOptions.

Returns:

CosmosClientBuilder atual

throttlingRetryOptions

public CosmosClientBuilder throttlingRetryOptions(ThrottlingRetryOptions throttlingRetryOptions)

Define as opções de política de repetição associadas à instância do DocumentClient.

As propriedades na classe RetryOptions permitem que o aplicativo personalize as políticas de repetição internas. Essa propriedade é opcional. Quando não está definido, o SDK usa os valores padrão para configurar as políticas de repetição. Consulte Classe RetryOptions para obter mais detalhes.

Parameters:

throttlingRetryOptions - a instância retryOptions.

Returns:

CosmosClientBuilder atual

userAgentSuffix

public CosmosClientBuilder userAgentSuffix(String userAgentSuffix)

define o valor do sufixo user-agent.

Parameters:

userAgentSuffix - O valor a ser acrescentado ao cabeçalho user-agent, que é usado para fins de monitoramento.

Returns:

CosmosClientBuilder atual

Aplica-se a