Partilhar via


CosmosClient Classe

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 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 instâncias do CosmosClient de inicialização 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 da 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 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 pedidos HTTP e respostas.

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 de 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

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

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 bases de dados georreplicadas. (Predefinição: Verdadeiro)

preferred_locations
list[str]

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

enable_diagnostics_logging
bool

Ative a política 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 a um único nível de pedido. Os pedidos serão registados ao nível da INFORMAÇÃO.

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 sã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 que são 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 de 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

Exceções

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

Exemplos

Criar 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 sã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 que são 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 a 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

Exceções

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 <xref:azure.cosmos.cosmos_client.DatabaseProxy> a instância 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

Exceções

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 da conta).

Exceções

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

get_database_account

Obtenha as informações da conta de 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

Exceções

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

Exceções

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

Exceções

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 como 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

Exceções

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