Compartilhar via

CosmosClient Classe

  • Referência

Uma representação lógica do lado do cliente de uma conta do Azure Cosmos DB.

Use esse cliente para configurar e executar solicitações para o serviço do Azure Cosmos DB.

É recomendável manter uma única instância do CosmosClient por tempo de vida do aplicativo, o que permite o gerenciamento e o desempenho de conexões eficientes.

A inicialização do CosmosClient é uma operação pesada – não use instâncias do CosmosClient de inicialização como credenciais ou validações de conectividade de rede.

Criar uma instância de um novo CosmosClient.

Herança
builtins.object
CosmosClient

Construtor

CosmosClient(url: str, credential: Any, consistency_level: str | None = None, **kwargs: Any)

Parâmetros

url
str
Obrigatório

A URL da conta do Cosmos DB.

credential
Union[str, Dict[str, str], TokenCredential]
Obrigatório

Pode ser a chave de conta ou um dicionário de tokens de recurso.

consistency_level
str
valor padrão: None

Nível de consistência a ser usado para a sessão. O valor padrão é None (Nível da conta). Mais informações sobre níveis de consistência e valores possíveis: https://aka.ms/cosmos-consistency-levels

timeout
int

Um tempo limite absoluto em segundos para o processamento combinado de solicitação HTTP e resposta.

connection_timeout
int

O tempo limite da solicitação HTTP em segundos.

connection_mode
str

O modo de conexão para o cliente – atualmente só dá suporte a 'Gateway'.

proxy_config
ProxyConfiguration

Configuração do proxy de conexão.

ssl_config
SSLConfiguration

Configuração de SSL de conexão.

connection_verify
bool

Se a conexão for verificada, o valor padrão será True.

connection_cert
str

Um certificado alternativo para verificar a conexão.

retry_total
int

Máximo de tentativas de repetição.

retry_backoff_max
int

Tempo máximo de espera de repetição em segundos.

retry_fixed_interval
int

Corrigido o intervalo de repetição em milissegundos.

retry_read
int

Número máximo de tentativas de repetição de leitura de soquete.

retry_connect
int

Número máximo de tentativas de repetição de erro de conexão.

retry_status
int

Número máximo de tentativas de repetição em códigos de status de erro.

retry_on_status_codes
list[int]

Uma lista de códigos de status específicos para tentar novamente.

retry_backoff_factor
float

Fator para calcular o tempo de espera entre tentativas de repetição.

enable_endpoint_discovery
bool

Habilite a descoberta de ponto de extremidade para contas de banco de dados replicadas geograficamente. (Padrão: True)

preferred_locations
list[str]

Os locais preferenciais para contas de banco de dados replicadas geograficamente.

enable_diagnostics_logging
bool

Habilite a política CosmosHttpLogging. Deve ser usado junto com um agente para funcionar.

logger
Logger

Agente a ser usado para coletar diagnóstico de solicitação. Pode ser passado no nível do cliente (para registrar todas as solicitações) ou em um único nível de solicitação. As solicitações serão registradas no nível info.

Exemplos

Crie uma nova instância do cliente do Cosmos DB:


   from azure.cosmos import exceptions, CosmosClient, PartitionKey

   import os

   url = os.environ["ACCOUNT_URI"]
   key = os.environ["ACCOUNT_KEY"]
   client = CosmosClient(url, key)

Métodos

create_database

Crie um novo banco de dados com a ID fornecida (nome).
create_database_if_not_exists

Crie o banco de dados se ele ainda não existir.

Se o banco de dados já existir, as configurações existentes serão retornadas.

.. observação:: essa função não marcar nem atualiza as configurações de banco de dados existentes ou a taxa de transferência da oferta se forem diferentes do que é passado.
delete_database

Exclua o banco de dados com a ID fornecida (nome).
from_connection_string

Crie uma instância do CosmosClient de uma cadeia de conexão.

Isso pode ser recuperado do portal do Azure. Para obter a lista completa de argumentos palavra-chave opcionais, consulte o construtor CosmosClient.
get_database_account

Recupere as informações da conta de banco de dados.
get_database_client

Recupere um banco de dados existente com a ID (nome).
list_databases

Liste os bancos de dados em uma conta de banco de dados SQL do Cosmos DB.
query_databases

Consulte os bancos de dados em uma conta de banco de dados SQL do Cosmos DB.

create_database

Crie um novo banco de dados com a ID fornecida (nome).

create_database(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

Parâmetros

id
Obrigatório

ID (nome) do banco de dados a ser criado.

offer_throughput
Obrigatório

A taxa de transferência provisionada para esta oferta.

session_token
str

Token para uso com consistência de sessão.

initial_headers
dict[str,str]

Cabeçalhos iniciais a serem enviados como parte da solicitação.

etag
str

Um valor de ETag ou o caractere curinga (*). Usado para marcar se o recurso foi alterado e agir de acordo com a condição especificada pelo parâmetro match_condition.

match_condition
MatchConditions

A condição de correspondência a ser usada na etag.

response_hook
Callable

Um callable invocado com os metadados de resposta.

Retornos

Uma instância databaseProxy que representa o novo banco de dados.

Tipo de retorno

DatabaseProxy

Exceções

CosmosResourceExistsError

O banco de dados com a ID fornecida já existe.

Exemplos

Crie um banco de dados na conta do Cosmos DB:


   database_name = "testDatabase"
   try:
       database = client.create_database(id=database_name)
   except exceptions.CosmosResourceExistsError:
       database = client.get_database_client(database=database_name)

create_database_if_not_exists

Crie o banco de dados se ele ainda não existir.

Se o banco de dados já existir, as configurações existentes serão retornadas.

.. observação:: essa função não marcar nem atualiza as configurações de banco de dados existentes ou a taxa de transferência da oferta se forem diferentes do que é passado.

create_database_if_not_exists(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

Parâmetros

id
Obrigatório

ID (nome) do banco de dados a ser lido ou criado.

populate_query_metrics
bool
Obrigatório

Habilite o retorno de métricas de consulta em cabeçalhos de resposta.

offer_throughput
int ou <xref:azure.cosmos.ThroughputProperties.>
Obrigatório

A taxa de transferência provisionada para esta oferta.

session_token
str

Token para uso com consistência de sessão.

initial_headers
dict[str,str]

Cabeçalhos iniciais a serem enviados como parte da solicitação.

etag
str

Um valor de ETag ou o caractere curinga (*). Usado para marcar se o recurso foi alterado e agir de acordo com a condição especificada pelo parâmetro match_condition.

match_condition
MatchConditions

A condição de correspondência a ser usada na etag.

response_hook
Callable

Um callable invocado com os metadados de resposta.

Retornos

Uma instância DatabaseProxy que representa o banco de dados.

Tipo de retorno

DatabaseProxy

Exceções

CosmosHttpResponseError

Falha na leitura ou criação do banco de dados.

delete_database

Exclua o banco de dados com a ID fornecida (nome).

delete_database(database: str | DatabaseProxy | Dict[str, Any], populate_query_metrics: bool | None = None, **kwargs: Any) -> None

Parâmetros

database
str ou dict(str, str) ou DatabaseProxy
Obrigatório

A ID (nome), dict que representa as propriedades ou <xref:azure.cosmos.cosmos_client.DatabaseProxy> a instância do banco de dados a ser excluída.

session_token
str

Token para uso com consistência de sessão.

initial_headers
dict[str,str]

Cabeçalhos iniciais a serem enviados como parte da solicitação.

etag
str

Um valor de ETag ou o caractere curinga (*). Usado para marcar se o recurso foi alterado e agir de acordo com a condição especificada pelo parâmetro match_condition.

match_condition
MatchConditions

A condição de correspondência a ser usada na etag.

response_hook
Callable

Um callable invocado com os metadados de resposta.

Tipo de retorno

None

Exceções

CosmosHttpResponseError

Se o banco de dados não puder ser excluído.

from_connection_string

Crie uma instância do CosmosClient de uma cadeia de conexão.

Isso pode ser recuperado do portal do Azure. Para obter a lista completa de argumentos palavra-chave opcionais, consulte o construtor CosmosClient.

from_connection_string(conn_str: str, credential: Any | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

Parâmetros

conn_str
str
Obrigatório

A cadeia de conexão.

credential
str ou dict(str, str)
valor padrão: None

Credenciais alternativas a serem usadas em vez da chave fornecida na cadeia de conexão.

consistency_level
Optional[str]
valor padrão: None

Nível de consistência a ser usado para a sessão. O valor padrão é None (Nível da conta).

Exceções

CosmosResourceExistsError

O banco de dados com a ID fornecida já existe.

get_database_account

Recupere as informações da conta de banco de dados.

get_database_account(**kwargs: Any) -> DatabaseAccount

Parâmetros

response_hook
Callable

Um callable invocado com os metadados de resposta.

Retornos

Uma instância DatabaseAccount que representa a conta de banco de dados do Cosmos DB.

Tipo de retorno

DatabaseAccount

Exceções

CosmosResourceExistsError

O banco de dados com a ID fornecida já existe.

get_database_client

Recupere um banco de dados existente com a ID (nome).

get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy

Parâmetros

database
str ou dict(str, str) ou DatabaseProxy
Obrigatório

A ID (nome), ditado que representa as propriedades ou a instância DatabaseProxy do banco de dados a ser lido.

Retornos

Uma instância databaseProxy que representa o banco de dados recuperado.

Tipo de retorno

DatabaseProxy

Exceções

CosmosResourceExistsError

O banco de dados com a ID fornecida já existe.

list_databases

Liste os bancos de dados em uma conta de banco de dados SQL do Cosmos DB.

list_databases(max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parâmetros

max_item_count
int
Obrigatório

Número máximo de itens a serem retornados na operação de enumeração.

session_token
str

Token para uso com consistência de sessão.

initial_headers
dict[str,str]

Cabeçalhos iniciais a serem enviados como parte da solicitação.

response_hook
Callable

Um callable invocado com os metadados de resposta.

Retornos

Uma iterável de propriedades de banco de dados (dicts).

Tipo de retorno

Iterable[dict[str, str]]

Exceções

CosmosResourceExistsError

O banco de dados com a ID fornecida já existe.

query_databases

Consulte os bancos de dados em uma conta de banco de dados SQL do Cosmos DB.

query_databases(query: str | None = None, parameters: List[Dict[str, Any]] | None = None, enable_cross_partition_query: bool | None = None, max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parâmetros

query
str
Obrigatório

A consulta SQL do Azure Cosmos DB a ser executada.

parameters
List[Dict[str, Any]]
Obrigatório

Matriz opcional de parâmetros para a consulta. Ignorado se nenhuma consulta for fornecida.

enable_cross_partition_query
bool
Obrigatório

Permitir verificação nas consultas que não puderam ser atendidas, pois a indexação foi recusada nos caminhos solicitados.

max_item_count
int
Obrigatório

Número máximo de itens a serem retornados na operação de enumeração.

session_token
str

Token para uso com consistência de sessão.

initial_headers
dict[str,str]

Cabeçalhos iniciais a serem enviados como parte da solicitação.

response_hook
Callable

Um callable invocado com os metadados de resposta.

Retornos

Uma iterável de propriedades de banco de dados (dicts).

Tipo de retorno

Iterable[dict[str, str]]

Exceções

CosmosResourceExistsError

O banco de dados com a ID fornecida já existe.