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