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

DatabaseProxy

Exceções

CosmosResourceExistsError

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

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

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

Exceções

CosmosResourceExistsError

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

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

Iterable[dict[str, str]]

Exceções

CosmosResourceExistsError

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