CosmosClient Classe

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.