DatabaseProxy Classe

Referência

Uma interface para interagir com uma base de dados específica.

Esta classe não deve ser instanciada diretamente. Em vez disso, utilize o <xref:azure.cosmos.aio.cosmos_client.CosmosClient.get_database_client> método para obter uma base de dados existente ou o <xref:azure.cosmos.aio.cosmos_client.CosmosClient.create_database> método para criar uma nova base de dados.

Uma base de dados contém um ou mais contentores, cada um dos quais pode conter itens, procedimentos armazenados, acionadores e funções definidas pelo utilizador.

Uma base de dados também pode ter utilizadores associados, cada um dos quais está configurado com um conjunto de permissões para aceder a determinados contentores, procedimentos armazenados, acionadores, funções definidas pelo utilizador ou itens.

Uma base de dados da API SQL do Azure Cosmos DB tem as seguintes propriedades geradas pelo sistema. Estas propriedades são só de leitura:

_rid: O ID do recurso.
_ts: quando o recurso foi atualizado pela última vez. O valor é um carimbo de data/hora.
_self: o URI endereçável exclusivo para o recurso.
_etag: o etag de recursos necessário para o controlo de simultaneidade otimista.
_colls: o caminho endereçável do recurso de coleções.
_users: o caminho endereçável do recurso dos utilizadores.

Herança: builtins.object

DatabaseProxy

Construtor

DatabaseProxy(client_connection: CosmosClientConnection, id: str, properties: Dict[str, Any] = None)

Parâmetros

client_connection: <xref:azure.cosmos.aio.CosmosClientConnection>

Necessário

Cliente a partir do qual esta base de dados foi obtida.

id: str

Necessário

ID (nome) da base de dados.

properties

valor predefinido: None

Variáveis

id

O ID (nome) da base de dados.

Métodos

create_container	Crie um novo contentor com o ID (nome) especificado. Se já existir um contentor com o ID especificado, é gerado um CosmosResourceExistsError.
create_container_if_not_exists	Crie um contentor se ainda não existir. Se o contentor já existir, as definições existentes são devolvidas. Nota: não verifica nem atualiza as definições de contentor existentes nem oferece débito se forem diferentes do que foi transmitido para o método .
create_user	Crie um novo utilizador no contentor. Para atualizar ou substituir um utilizador existente, utilize o <xref:ContainerProxy.upsert_user> método .
delete_container	Eliminar um contentor.
delete_user	Elimine o utilizador especificado do contentor.
get_container_client	Obtenha um ContainerProxy para um contentor com o ID (nome) especificado.
get_throughput	Obtenha o objeto ThroughputProperties para esta base de dados. Se ainda não existirem ThroughputProperties para a base de dados, é gerada uma exceção.
get_user_client	Obtenha um UserProxy para um utilizador com o ID especificado.
list_containers	Listar os contentores na base de dados.
list_users	Liste todos os utilizadores no contentor.
query_containers	Liste as propriedades dos contentores na base de dados atual.
query_users	Devolver todos os utilizadores que correspondam à consulta especificada.
read	Leia as propriedades da base de dados.
replace_container	Reponha as propriedades do contentor. As alterações de propriedade são mantidas imediatamente. Quaisquer propriedades não especificadas serão repostas para os respetivos valores predefinidos.
replace_throughput	Substitua o débito ao nível da base de dados. Se ainda não existirem ThroughputProperties para a base de dados, é gerada uma exceção.
replace_user	Substitui o utilizador especificado se existir no contentor.
upsert_user	Insira ou atualize o utilizador especificado. Se o utilizador já existir no contentor, este será substituído. Se o utilizador ainda não existir, é inserido.

create_container

Crie um novo contentor com o ID (nome) especificado.

Se já existir um contentor com o ID especificado, é gerado um CosmosResourceExistsError.

async create_container(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxy

Parâmetros

id: str

Necessário

ID (nome) do contentor a criar.

partition_key: PartitionKey

Necessário

A chave de partição a utilizar para o contentor.

indexing_policy: dict[str, str]

A política de indexação a aplicar ao contentor.

default_ttl: int

Time to live (TTL) predefinido para itens no contentor. Se não for especificado, os itens não expiram.

offer_throughput: Union[int, ThroughputProperties]

O débito aprovisionado para esta oferta.

unique_key_policy: dict[str, str]

A política de chave exclusiva a aplicar ao contentor.

conflict_resolution_policy: dict[str, str]

A política de resolução de conflitos a aplicar ao contentor.

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.

analytical_storage_ttl: int

Armazenamento analítico time to live (TTL) para itens no contentor. Um valor de Nenhum deixa o armazenamento analítico desativado e um valor de -1 ativa o armazenamento analítico sem TTL. Tenha em atenção que o armazenamento analítico só pode ser ativado em Synapse Link contas ativadas.

Devoluções

Uma instância do ContainerProxy que representa o novo contentor.

Tipo de retorno

ContainerProxy

Exceções

CosmosHttpResponseError

A criação do contentor falhou.

Exemplos

Criar um contentor com predefinições:


           container_name = "products"
           try:
               container = await database.create_container(
                   id=container_name, partition_key=PartitionKey(path="/productName")
               )
           except exceptions.CosmosResourceExistsError:
               container = database.get_container_client(container_name)

Criar um contentor com definições específicas; neste caso, uma chave de partição personalizada:


           customer_container_name = "customers"
           try:
               customer_container = await database.create_container(
                   id=customer_container_name,
                   partition_key=PartitionKey(path="/city"),
                   default_ttl=200,
               )
           except exceptions.CosmosResourceExistsError:
               customer_container = database.get_container_client(customer_container_name)

create_container_if_not_exists

Crie um contentor se ainda não existir.

Se o contentor já existir, as definições existentes são devolvidas. Nota: não verifica nem atualiza as definições de contentor existentes nem oferece débito se forem diferentes do que foi transmitido para o método .

async create_container_if_not_exists(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxy

Parâmetros

id: str

Necessário

ID (nome) do contentor a criar.

partition_key: PartitionKey

Necessário

A chave de partição a utilizar para o contentor.

indexing_policy: dict[str, str]

A política de indexação a aplicar ao contentor.

default_ttl: int

Time to live (TTL) predefinido para itens no contentor. Se não for especificado, os itens não expiram.

offer_throughput: Union[int, ThroughputProperties]

O débito aprovisionado para esta oferta.

unique_key_policy: dict[str, str]

A política de chave exclusiva a aplicar ao contentor.

conflict_resolution_policy: dict[str, str]

A política de resolução de conflitos a aplicar ao contentor.

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.

analytical_storage_ttl: int

Devoluções

Uma instância do ContainerProxy que representa o novo contentor.

Tipo de retorno

ContainerProxy

Exceções

CosmosHttpResponseError

A criação do contentor falhou.

create_user

Crie um novo utilizador no contentor.

Para atualizar ou substituir um utilizador existente, utilize o <xref:ContainerProxy.upsert_user> método .

async create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

Parâmetros

body: Dict[str, Any]

Necessário

Um objeto semelhante a um dict com uma chave de ID e um valor que representa o utilizador a ser criado. O ID de utilizador tem de ser exclusivo na base de dados e não ter mais de 255 carateres.

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

Um callable invocado com os metadados de resposta.

Devoluções

Uma instância do UserProxy que representa o novo utilizador.

Tipo de retorno

UserProxy

Exceções

CosmosHttpResponseError

Se não foi possível criar o utilizador especificado.

Exemplos

Criar um utilizador de base de dados:


           try:
               await database.create_user(dict(id="Walter Harp"))
               print("Created user Walter Harp.")
           except exceptions.CosmosResourceExistsError:
               print("A user with that ID already exists.")
           except exceptions.CosmosHttpResponseError as failure:
               print("Failed to create user. Status code:{}".format(failure.status_code))

delete_container

Eliminar um contentor.

async delete_container(container: str | ContainerProxy | Dict[str, Any], **kwargs: Any) -> None

Parâmetros

container: str ou Dict[str, Any] ou ContainerProxy

Necessário

O ID (nome) do contentor a eliminar. Pode transmitir o ID do contentor para eliminar, uma ContainerProxy instância ou um ditado que represente as propriedades do contentor.

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

Um callable invocado com os metadados de resposta.

Tipo de retorno

None

Exceções

CosmosHttpResponseError

Se não foi possível eliminar o contentor.

delete_user

Elimine o utilizador especificado do contentor.

async delete_user(user: str | UserProxy | Dict[str, Any], **kwargs: Any) -> None

Parâmetros

user: Union[str, Dict[str, Any], UserProxy]

Necessário

O ID (nome), o ditado que representa as propriedades ou UserProxy a instância do utilizador a eliminar.

response_hook: Callable[[Dict[str, str], None], None]

Um callable invocado com os metadados de resposta.

Tipo de retorno

None

Exceções

CosmosHttpResponseError

O utilizador não foi eliminado com êxito.

CosmosResourceNotFoundError

O utilizador não existe no contentor.

get_container_client

Obtenha um ContainerProxy para um contentor com o ID (nome) especificado.

get_container_client(container: str | ContainerProxy | Dict[str, Any]) -> ContainerProxy

Parâmetros

container: Union[str, Dict[str, Any], ContainerProxy]

Necessário

O ID (nome), o ditado que representa as propriedades ou ContainerProxy a instância do contentor a obter.

Devoluções

Uma instância do ContainerProxy que representa o contentor.

Tipo de retorno

ContainerProxy

Exceções

CosmosHttpResponseError

A criação do contentor falhou.

Exemplos

Obtenha um contentor existente, lidar com uma falha se for encontrado:


           database = client.get_database_client(database_name)
           container = database.get_container_client(container_name)

get_throughput

Obtenha o objeto ThroughputProperties para esta base de dados.

Se ainda não existirem ThroughputProperties para a base de dados, é gerada uma exceção.

async get_throughput(**kwargs: Any) -> ThroughputProperties

Parâmetros

response_hook: Callable[[Dict[str, str], List[Dict[str, Any]]], None]

Um callable invocado com os metadados de resposta.

Devoluções

ThroughputProperties para a base de dados.

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

Não foi possível obter propriedades de débito para a base de dados ou as propriedades de débito.

get_user_client

Obtenha um UserProxy para um utilizador com o ID especificado.

get_user_client(user: str | UserProxy | Dict[str, Any]) -> UserProxy

Parâmetros

user: Union[str, Dict[str, Any], UserProxy]

Necessário

O ID (nome), o ditado que representa as propriedades ou UserProxy a instância do utilizador a obter.

Devoluções

Uma instância do UserProxy que representa o utilizador recuperado.

Tipo de retorno

UserProxy

Exceções

CosmosHttpResponseError

A criação do contentor falhou.

list_containers

Listar os contentores na base de dados.

list_containers(**kwargs) -> 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], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Um AsyncItemPaged de propriedades de contentor (dicts).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

A criação do contentor falhou.

Exemplos

Listar todos os contentores na base de dados:


           database = client.get_database_client(database_name)
           async for container in database.list_containers():
               print("Container ID: {}".format(container['id']))

list_users

Liste todos os utilizadores no contentor.

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

Parâmetros

max_item_count: int

Número máximo de utilizadores a devolver na operação de enumeração.

response_hook: Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Um AsyncItemPaged de propriedades de utilizador (dicts).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

A criação do contentor falhou.

query_containers

Liste as propriedades dos contentores na base de dados atual.

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

Parâmetros

query: Union[str, Dict[str, Any]]

A consulta SQL do Azure Cosmos DB a executar.

parameters: Optional[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], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Um AsyncItemPaged de propriedades de contentor (dicts).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

A criação do contentor falhou.

query_users

Devolver todos os utilizadores que correspondam à consulta especificada.

query_users(query: str | Dict[str, Any], **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parâmetros

query: Union[str, Dict[str, Any]]

Necessário

A consulta SQL do Azure Cosmos DB a executar.

parameters: Optional[List[Dict[str, Any]]]

Matriz opcional de parâmetros para a consulta. Cada parâmetro é um dict() com chaves "name" e "value". Ignorado se não for fornecida nenhuma consulta.

max_item_count: int

Número máximo de utilizadores a devolver na operação de enumeração.

response_hook: Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Um AsyncItemPaged de propriedades de utilizador (dicts).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

A criação do contentor falhou.

read

Leia as propriedades da base de dados.

async read(**kwargs: Any) -> Dict[str, Any]

Parâmetros

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

Um callable invocado com os metadados de resposta.

Devoluções

Um ditado que representa as propriedades da base de dados

Tipo de retorno

Dict[str, Any]

Exceções

CosmosHttpResponseError

Se não foi possível obter a base de dados especificada.

replace_container

Reponha as propriedades do contentor.

As alterações de propriedade são mantidas imediatamente. Quaisquer propriedades não especificadas serão repostas para os respetivos valores predefinidos.

async replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: PartitionKey, **kwargs: Any) -> ContainerProxy

Parâmetros

container: Union[str, Dict[str, Any], ContainerProxy]

Necessário

O ID (nome), o ditado que representa as propriedades ou ContainerProxy instâncias do contentor a substituir.

partition_key: PartitionKey

Necessário

A chave de partição a utilizar para o contentor.

indexing_policy: dict[str, str]

A política de indexação a aplicar ao contentor.

default_ttl: int

Tempo de vida predefinido (TTL) para itens no contentor. Se não for especificado, os itens não expiram.

conflict_resolution_policy: dict[str, str]

A política de resolução de conflitos a aplicar ao contentor.

session_token: str

Token para utilização com consistência de sessão.

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.

initial_headers: dict[str, str]

Cabeçalhos iniciais a serem enviados como parte do pedido.

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

Um callable invocado com os metadados de resposta.

analytical_storage_ttl: int

Tempo de armazenamento analítico em direto (TTL) para itens no contentor. Um valor de Nenhum deixa o armazenamento analítico desativado e um valor de -1 ativa o armazenamento analítico sem TTL. Tenha em atenção que o armazenamento analítico só pode ser ativado em contas Synapse Link ativadas.

Devoluções

Uma instância do ContainerProxy que representa o contentor após a substituição concluída.

Tipo de retorno

ContainerProxy

Exceções

CosmosHttpResponseError

Gerado se o contentor não puder ser substituído. Isto inclui se o contentor com o ID especificado não existir.

Exemplos

Reponha a propriedade TTL num contentor e apresente as propriedades atualizadas:


           # Set the TTL on the container to 3600 seconds (one hour)
           await database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)

           # Display the new TTL setting for the container
           container_props = await database.get_container_client(container_name).read()
           print("New container TTL: {}".format(json.dumps(container_props['defaultTtl'])))

replace_throughput

Substitua o débito ao nível da base de dados.

Se ainda não existirem ThroughputProperties para a base de dados, é gerada uma exceção.

async replace_throughput(throughput: int | ThroughputProperties, **kwargs: Any) -> ThroughputProperties

Parâmetros

throughput: Union[int, ThroughputProperties]

Necessário

O débito a definir.

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

Um callable invocado com os metadados de resposta.

Devoluções

ThroughputProperties para a base de dados, atualizado com novo débito.

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

Não existem propriedades de débito para a base de dados ou as propriedades de débito não puderam ser atualizadas.

replace_user

Substitui o utilizador especificado se existir no contentor.

async replace_user(user: str | UserProxy | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxy

Parâmetros

user: Union[str, Dict[str, Any], UserProxy]

Necessário

O ID (nome), o ditado que representa as propriedades ou UserProxy instâncias do utilizador a substituir.

body: Dict[str, Any]

Necessário

Um objeto semelhante a um ditado que representa o utilizador a substituir.

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

Um callable invocado com os metadados de resposta.

Devoluções

Uma instância do UserProxy que representa o utilizador após a substituição.

Tipo de retorno

UserProxy

Exceções

CosmosHttpResponseError

Se a substituição tiver falhado ou o utilizador com o ID especificado não existir.

upsert_user

Insira ou atualize o utilizador especificado.

Se o utilizador já existir no contentor, este será substituído. Se o utilizador ainda não existir, é inserido.

async upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

Parâmetros

body: Dict[str, Any]

Necessário

Um objeto semelhante a um ditado que representa o utilizador para atualizar ou inserir.

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

Um callable invocado com os metadados de resposta.

Devoluções

Uma instância do UserProxy que representa o utilizador upserted.

Tipo de retorno

UserProxy

Exceções

CosmosHttpResponseError

Se não for possível atualizar o utilizador especificado.

Partilhar via

DatabaseProxy Classe

Construtor

Parâmetros

Variáveis

Métodos

create_container

Parâmetros

Devoluções

Tipo de retorno

Exceções

Exemplos

create_container_if_not_exists

Parâmetros

Devoluções

Tipo de retorno

Exceções

create_user

Parâmetros

Devoluções

Tipo de retorno

Exceções

Exemplos

delete_container

Parâmetros

Tipo de retorno

Exceções

delete_user

Parâmetros

Tipo de retorno

Exceções

get_container_client

Parâmetros

Devoluções

Tipo de retorno

Exceções

Exemplos

get_throughput

Parâmetros

Devoluções

Tipo de retorno

Exceções

get_user_client

Parâmetros

Devoluções

Tipo de retorno

Exceções

list_containers

Parâmetros

Devoluções

Tipo de retorno

Exceções

Exemplos

list_users

Parâmetros

Devoluções

Tipo de retorno

Exceções

query_containers

Parâmetros

Devoluções

Tipo de retorno

Exceções

query_users

Parâmetros

Devoluções

Tipo de retorno

Exceções

read

Parâmetros

Devoluções

Tipo de retorno

Exceções

replace_container

Parâmetros

Devoluções

Tipo de retorno

Exceções

Exemplos

replace_throughput