CosmosClient Classe

Referência

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

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

Partilhar via

CosmosClient Classe

Construtor

Parâmetros

Exemplos

Métodos

close

create_database

Parâmetros

Devoluções

Tipo de retorno

Exceções

Exemplos

create_database_if_not_exists

Parâmetros

Devoluções

Tipo de retorno

Exceções

delete_database

Parâmetros

Tipo de retorno

Exceções

from_connection_string

Parâmetros

Devoluções

Tipo de retorno

get_database_client

Parâmetros

Devoluções

Tipo de retorno

list_databases

Parâmetros

Devoluções

Tipo de retorno

query_databases

Parâmetros

Devoluções

Tipo de retorno

Recursos adicionais