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: str | Dict[str, str] | TokenCredential, *, 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], AsyncTokenCredential]

Necessário

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

consistency_level

str

Nível de consistência a utilizar para a sessão. O valor predefinido é Nenhum (ao 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:

       async with CosmosClient(url, key) as client:

Métodos

close	Feche esta instância do CosmosClient.
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_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.

close

Feche esta instância do CosmosClient.

async close() -> None

create_database

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

async create_database(id: str, **kwargs: Any) -> DatabaseProxy

Parâmetros

id

str

Necessário

ID (nome) da base de dados a criar.

offer_throughput

Union[int, ThroughputProperties]

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[[Dict[str, str], Dict[str, Any]], None]

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

async create_database_if_not_exists(id: str, **kwargs: Any) -> DatabaseProxy

Parâmetros

id

str

Necessário

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

offer_throughput

Union[int, ThroughputProperties]

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[[Dict[str, str], Dict[str, Any]], None]

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.

async delete_database(database: str | DatabaseProxy | Dict[str, Any], **kwargs: Any) -> None

Parâmetros

database

Union[str, DatabaseProxy, Dict[str, Any]]

Necessário

O ID (nome), o ditado que representa as propriedades ou 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[[Dict[str, str]], None]

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: str | Dict[str, str] | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

Parâmetros

conn_str

str

Necessário

A cadeia de ligação.

credential

Union[str, Dict[str, str]]

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

consistency_level

str

Nível de consistência a utilizar para a sessão. O valor predefinido é Nenhum (ao nível da conta). Mais informações sobre níveis de consistência e valores possíveis: https://aka.ms/cosmos-consistency-levels

Devoluções

uma instância do CosmosClient

Tipo de retorno

CosmosClient

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

Union[str, DatabaseProxy, Dict[str, Any]]

Necessário

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

Devoluções

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

Tipo de retorno

DatabaseProxy

list_databases

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

list_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parâmetros

max_item_count

int

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[[Dict[str, str]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Um AsyncItemPaged de propriedades da base de dados (dicts).

Tipo de retorno

<xref:AsyncItemPaged>[Dict[str, str]]

query_databases

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

query_databases(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parâmetros

query

Union[str, Dict[str, Any]]

A consulta SQL do Azure Cosmos DB a executar.

parameters

List[Dict[str, Any]]

Matriz opcional de parâmetros para a consulta. Cada parâmetro é um dict() com chaves "name" e "value".

max_item_count

int

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[[Dict[str, str]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Um AsyncItemPaged de propriedades da base de dados (dicts).

Tipo de retorno

<xref:AsyncItemPaged>[Dict[str, str]]