CosmosClient Classe

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

Use esse cliente para configurar e executar solicitações para o serviço do Azure Cosmos DB.

É recomendável manter uma única instância do CosmosClient por tempo de vida do aplicativo, o que permite o gerenciamento e o desempenho de conexões eficientes.

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

Criar uma instância de 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

Obrigatório

A URL da conta do Cosmos DB.

credential

Union[str, Dict[str, str], AsyncTokenCredential]

Obrigatório

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

consistency_level

str

Nível de consistência a ser usado para a sessão. O valor padrão é None (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 processamento combinado de solicitação HTTP e resposta.

connection_timeout

int

O tempo limite da solicitação HTTP em segundos.

connection_mode

str

O modo de conexão para o cliente – atualmente só dá suporte a 'Gateway'.

proxy_config

ProxyConfiguration

Configuração do proxy de conexão.

ssl_config

SSLConfiguration

Configuração de SSL de conexão.

connection_verify

bool

Se a conexão for verificada, o valor padrão será True.

connection_cert

str

Um certificado alternativo para verificar a conexã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

Corrigido o intervalo de repetição em milissegundos.

retry_read

int

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

retry_connect

int

Número máximo de tentativas de repetição de erro de conexão.

retry_status

int

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

retry_on_status_codes

list[int]

Uma lista de códigos de status específicos para tentar novamente.

retry_backoff_factor

float

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

enable_endpoint_discovery

bool

Habilite a descoberta de ponto de extremidade para contas de banco de dados replicadas geograficamente. (Padrão: True)

preferred_locations

list[str]

Os locais preferenciais para contas de banco de dados replicadas geograficamente.

enable_diagnostics_logging

bool

Habilite a política CosmosHttpLogging. Deve ser usado junto com um agente para funcionar.

logger

Logger

Agente a ser usado para coletar diagnóstico de solicitação. Pode ser passado no nível do cliente (para registrar todas as solicitações) ou em um único nível de solicitação. As solicitações serão registradas no nível info.

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 um novo banco de dados com a ID fornecida (nome).
create_database_if_not_exists	Crie o banco de dados se ele ainda não existir. Se o banco de dados já existir, as configurações existentes serão retornadas. .. observação:: essa função não marcar nem atualiza as configurações de banco de dados existentes ou a taxa de transferência da oferta se forem diferentes do que é passado.
delete_database	Exclua o banco de dados com a ID fornecida (nome).
from_connection_string	Crie uma instância do CosmosClient de uma cadeia de conexão. Isso pode ser recuperado do portal do Azure. Para obter a lista completa de argumentos palavra-chave opcionais, consulte o construtor CosmosClient.
get_database_client	Recupere um banco de dados existente com a ID (nome).
list_databases	Liste os bancos de dados em uma conta de banco de dados SQL do Cosmos DB.
query_databases	Consulte os bancos de dados em uma conta de banco de dados SQL do Cosmos DB.

close

Feche esta instância do CosmosClient.

async close() -> None

create_database

Crie um novo banco de dados com a ID fornecida (nome).

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

Parâmetros

id

str

Obrigatório

ID (nome) do banco de dados a ser criado.

offer_throughput

Union[int, ThroughputProperties]

A taxa de transferência provisionada para esta oferta.

session_token

str

Token para uso com consistência de sessão.

initial_headers

dict[str, str]

Cabeçalhos iniciais a serem enviados como parte da solicitação.

etag

str

Um valor de ETag ou o caractere curinga (*). Usado para marcar 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 ser usada na etag.

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

Um callable invocado com os metadados de resposta.

Retornos

Uma instância databaseProxy que representa o novo banco de dados.

Tipo de retorno

DatabaseProxy

Exceções

CosmosResourceExistsError

O banco de dados com a ID fornecida já existe.

Exemplos

Crie um banco 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 o banco de dados se ele ainda não existir.

Se o banco de dados já existir, as configurações existentes serão retornadas.

.. observação:: essa função não marcar nem atualiza as configurações de banco de dados existentes ou a taxa de transferência da oferta se forem diferentes do que é passado.

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

Parâmetros

id

str

Obrigatório

ID (nome) do banco de dados a ser lido ou criado.

offer_throughput

Union[int, ThroughputProperties]

A taxa de transferência provisionada para esta oferta.

session_token

str

Token para uso com consistência de sessão.

initial_headers

dict[str, str]

Cabeçalhos iniciais a serem enviados como parte da solicitação.

etag

str

Um valor de ETag ou o caractere curinga (*). Usado para marcar 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 ser usada na etag.

response_hook

Callable[[Dict[str, str], Dict[str, Any]], None]

Um callable invocado com os metadados de resposta.

Retornos

Uma instância DatabaseProxy que representa o banco de dados.

Tipo de retorno

DatabaseProxy

Exceções

CosmosHttpResponseError

Falha na leitura ou criação do banco de dados.

delete_database

Exclua o banco de dados com a ID fornecida (nome).

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

Parâmetros

database

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

Obrigatório

A ID (nome), dict que representa as propriedades ou DatabaseProxy a instância do banco de dados a ser excluída.

session_token

str

Token para uso com consistência de sessão.

initial_headers

dict[str, str]

Cabeçalhos iniciais a serem enviados como parte da solicitação.

etag

str

Um valor de ETag ou o caractere curinga (*). Usado para marcar 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 ser usada na etag.

response_hook

Callable[[Dict[str, str]], None]

Um callable invocado com os metadados de resposta.

Tipo de retorno

None

Exceções

CosmosHttpResponseError

Se o banco de dados não puder ser excluído.

from_connection_string

Crie uma instância do CosmosClient de uma cadeia de conexão.

Isso pode ser recuperado do portal do Azure. Para obter a lista completa de argumentos palavra-chave opcionais, consulte 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

Obrigatório

A cadeia de conexão.

credential

Union[str, Dict[str, str]]

Credenciais alternativas a serem usadas em vez da chave fornecida na cadeia de conexão.

consistency_level

str

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

Retornos

uma instância do CosmosClient

Tipo de retorno

CosmosClient

get_database_client

Recupere um banco de dados existente com a ID (nome).

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

Parâmetros

database

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

Obrigatório

A ID (nome), dict que representa as propriedades ou DatabaseProxy a instância do banco de dados a ser obtido.

Retornos

Uma instância databaseProxy que representa o banco de dados recuperado.

Tipo de retorno

DatabaseProxy

list_databases

Liste os bancos de dados em uma conta de banco 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 serem retornados na operação de enumeração.

session_token

str

Token para uso com consistência de sessão.

initial_headers

dict[str, str]

Cabeçalhos iniciais a serem enviados como parte da solicitação.

response_hook

Callable[[Dict[str, str]], None]

Um callable invocado com os metadados de resposta.

Retornos

Um AsyncItemPaged de propriedades de banco de dados (dicts).

Tipo de retorno

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

query_databases

Consulte os bancos de dados em uma conta de banco 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 ser executada.

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 serem retornados na operação de enumeração.

session_token

str

Token para uso com consistência de sessão.

initial_headers

dict[str, str]

Cabeçalhos iniciais a serem enviados como parte da solicitação.

response_hook

Callable[[Dict[str, str]], None]

Um callable invocado com os metadados de resposta.

Retornos

Um AsyncItemPaged de propriedades de banco de dados (dicts).

Tipo de retorno

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