CosmosClient Classe

  • Referência

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

Utilize este cliente para configurar e executar pedidos para o serviço do Azure Cosmos DB.

Recomenda-se manter uma única instância do CosmosClient por duração da aplicação, o que permite uma gestão e desempenho de ligações eficientes.

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

Instanciar 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
Necessário

O URL da conta do Cosmos DB.

credential
Union[str, Dict[str, str], TokenCredential]
Necessário

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

consistency_level
str
valor predefinido: None

Nível de consistência a utilizar para a sessão. O valor predefinido é Nenhum (Nível de 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 pedido HTTP combinado e o processamento de resposta.

connection_timeout
int

O tempo limite do pedido HTTP em segundos.

connection_mode
str

O modo de ligação para o cliente – atualmente só suporta "Gateway".

proxy_config
ProxyConfiguration

Configuração do proxy de ligação.

ssl_config
SSLConfiguration

Configuração do SSL de ligação.

connection_verify
bool

Se pretende verificar a ligação, o valor predefinido é Verdadeiro.

connection_cert
str

Um certificado alternativo para verificar a ligação.

retry_total
int

Tentativas de repetição máximas.

retry_backoff_max
int

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

retry_fixed_interval
int

Foi corrigido o intervalo de repetição em milissegundos.

retry_read
int

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

retry_connect
int

Número máximo de tentativas de repetição de erros de ligação.

retry_status
int

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

retry_on_status_codes
list[int]

Uma lista de códigos de estado específicos a repetir.

retry_backoff_factor
float

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

enable_endpoint_discovery
bool

Ative a deteção de pontos finais para contas de base de dados georreplicadas. (Predefinição: Verdadeiro)

preferred_locations
list[str]

As localizações preferenciais para contas de base de dados georreplicadas.

enable_diagnostics_logging
bool

Ative a política do CosmosHttpLogging. Tem de ser utilizado juntamente com um logger para trabalhar.

logger
Logger

Logger a ser utilizado para recolher diagnósticos de pedidos. Pode ser transmitido ao nível do cliente (para registar todos os pedidos) ou num único nível de pedido. Os pedidos serão registados ao nível da 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 uma nova base de dados com o ID (nome) especificado.
create_database_if_not_exists

Crie a base de dados se ainda não existir.

Se a base de dados já existir, as definições existentes serão devolvidas.

.. nota: esta função não verifica nem atualiza as definições de base de dados existentes nem oferece débito se forem diferentes das transmitidas.
delete_database

Elimine a base de dados com o ID (nome) especificado.
from_connection_string

Crie uma instância do CosmosClient a partir de uma cadeia de ligação.

Isto pode ser obtido a partir do portal do Azure. Para obter uma lista completa dos argumentos de palavra-chave opcionais, veja o construtor cosmosClient.
get_database_account

Obtenha as informações da conta da base de dados.
get_database_client

Obtenha uma base de dados existente com o ID (nome).
list_databases

Liste as bases de dados numa conta de base de dados SQL do Cosmos DB.
query_databases

Consulte as bases de dados numa conta de base de dados SQL do Cosmos DB.

create_database

Crie uma nova base de dados com o ID (nome) especificado.

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

Parâmetros

id
Necessário

ID (nome) da base de dados a criar.

offer_throughput
Necessário

O débito aprovisionado para esta oferta.

session_token
str

Token para utilização com consistência de sessão.

initial_headers
dict[str,str]

Cabeçalhos iniciais a serem enviados como parte do pedido.

etag
str

Um valor ETag ou o caráter universal (*). Utilizado para verificar 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 utilizar no etag.

response_hook
Callable

Um callable invocado com os metadados de resposta.

Devoluções

Uma instância do DatabaseProxy que representa a nova base de dados.

Tipo de retorno

DatabaseProxy

Exceções

CosmosResourceExistsError

A base de dados com o ID especificado já existe.

Exemplos

Crie uma base 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 a base de dados se ainda não existir.

Se a base de dados já existir, as definições existentes serão devolvidas.

.. nota: esta função não verifica nem atualiza as definições de base de dados existentes nem oferece débito se forem diferentes das transmitidas.

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
Necessário

ID (nome) da base de dados para ler ou criar.

populate_query_metrics
bool
Necessário

Ative a devolução de métricas de consulta nos cabeçalhos de resposta.

offer_throughput
int ou <xref:azure.cosmos.ThroughputProperties.>
Necessário

O débito aprovisionado para esta oferta.

session_token
str

Token para utilização com consistência de sessão.

initial_headers
dict[str,str]

Cabeçalhos iniciais a serem enviados como parte do pedido.

etag
str

Um valor ETag ou o caráter universal (*). Utilizado para verificar 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 utilizar no etag.

response_hook
Callable

Um callable invocado com os metadados de resposta.

Devoluções

Uma instância do DatabaseProxy que representa a base de dados.

Tipo de retorno

DatabaseProxy

Exceções

CosmosHttpResponseError

A leitura ou criação da base de dados falhou.

delete_database

Elimine a base de dados com o ID (nome) especificado.

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
Necessário

O ID (nome), o ditado que representa as propriedades ou DatabaseProxy instâncias da base de dados a eliminar.

session_token
str

Token para utilização com consistência de sessão.

initial_headers
dict[str,str]

Cabeçalhos iniciais a serem enviados como parte do pedido.

etag
str

Um valor ETag ou o caráter universal (*). Utilizado para verificar 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 utilizar no etag.

response_hook
Callable

Um callable invocado com os metadados de resposta.

Tipo de retorno

None

Exceções

CosmosHttpResponseError

Se não foi possível eliminar a base de dados.

from_connection_string

Crie uma instância do CosmosClient a partir de uma cadeia de ligação.

Isto pode ser obtido a partir do portal do Azure. Para obter uma lista completa dos argumentos de palavra-chave opcionais, veja 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
Necessário

A cadeia de ligação.

credential
str ou dict(str, str)
valor predefinido: None

Credenciais alternativas a utilizar em vez da chave fornecida na cadeia de ligação.

consistency_level
Optional[str]
valor predefinido: None

Nível de consistência a utilizar para a sessão. O valor predefinido é Nenhum (Nível de conta).

Exceções

CosmosResourceExistsError

A base de dados com o ID especificado já existe.

get_database_account

Obtenha as informações da conta da base de dados.

get_database_account(**kwargs: Any) -> DatabaseAccount

Parâmetros

response_hook
Callable

Um callable invocado com os metadados de resposta.

Devoluções

Uma instância databaseAccount que representa a Conta de Base de Dados do Cosmos DB.

Tipo de retorno

DatabaseAccount

Exceções

CosmosResourceExistsError

A base de dados com o ID especificado já existe.

get_database_client

Obtenha uma base de dados existente com o ID (nome).

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

Parâmetros

database
str ou dict(str, str) ou DatabaseProxy
Necessário

O ID (nome), o ditado que representa as propriedades ou a instância databaseProxy da base de dados a ler.

Devoluções

Uma instância do DatabaseProxy que representa a base de dados obtida.

Tipo de retorno

DatabaseProxy

Exceções

CosmosResourceExistsError

A base de dados com o ID especificado já existe.

list_databases

Liste as bases de dados numa conta de base 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
Necessário

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

session_token
str

Token para utilização com consistência de sessão.

initial_headers
dict[str,str]

Cabeçalhos iniciais a serem enviados como parte do pedido.

response_hook
Callable

Um callable invocado com os metadados de resposta.

Devoluções

Iterável de propriedades da base de dados (dicts).

Tipo de retorno

Iterable[dict[str, str]]

Exceções

CosmosResourceExistsError

A base de dados com o ID especificado já existe.

query_databases

Consulte as bases de dados numa conta de base 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
Necessário

A consulta SQL do Azure Cosmos DB a executar.

parameters
List[Dict[str, Any]]
Necessário

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

enable_cross_partition_query
bool
Necessário

Permitir a análise nas consultas que não puderam ser servidas porque a indexação foi desativada nos caminhos pedidos.

max_item_count
int
Necessário

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

session_token
str

Token para utilização com consistência de sessão.

initial_headers
dict[str,str]

Cabeçalhos iniciais a serem enviados como parte do pedido.

response_hook
Callable

Um callable invocado com os metadados de resposta.

Devoluções

Iterável de propriedades da base de dados (dicts).

Tipo de retorno

Iterable[dict[str, str]]

Exceções

CosmosResourceExistsError

A base de dados com o ID especificado já existe.