DatabaseProxy Classe

  • Referência

Uma interface para interagir com um banco de dados específico.

Essa classe não deve ser instanciada diretamente. Em vez disso, use o <xref:azure.cosmos.aio.cosmos_client.CosmosClient.get_database_client> método para obter um banco de dados existente ou o <xref:azure.cosmos.aio.cosmos_client.CosmosClient.create_database> método para criar um novo banco de dados.

Um banco de dados contém um ou mais contêineres, cada um deles pode conter itens, procedimentos armazenados, gatilhos e funções definidas pelo usuário.

Um banco de dados também pode ter usuários associados, cada um deles configurado com um conjunto de permissões para acessar determinados contêineres, procedimentos armazenados, gatilhos, funções definidas pelo usuário ou itens.

Um banco de dados da API de SQL do Azure Cosmos DB tem as propriedades geradas pelo sistema a seguir. Essas propriedades são somente leitura:

  • _rid: a 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: a etag de recurso necessária para o controle de simultaneidade otimista.

  • _colls: o caminho endereçável do recurso de coleções.

  • _users: o caminho endereçável do recurso de usuários.

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>
Obrigatório

Cliente do qual esse banco de dados foi recuperado.

id
str
Obrigatório

ID (nome) do banco de dados.

properties
valor padrão: None

Variáveis

id

A ID (nome) do banco de dados.

Métodos

create_container

Crie um novo contêiner com a ID fornecida (nome).

Se um contêiner com a ID fornecida já existir, um CosmosResourceExistsError será gerado.
create_container_if_not_exists

Crie um contêiner se ele ainda não existir.

Se o contêiner já existir, as configurações existentes serão retornadas. Observação: ele não marcar nem atualiza as configurações de contêiner existentes ou a taxa de transferência da oferta se forem diferentes do que foi passado para o método .
create_user

Crie um novo usuário no contêiner.

Para atualizar ou substituir um usuário existente, use o <xref:ContainerProxy.upsert_user> método .
delete_container

Excluir um contêiner.
delete_user

Exclua o usuário especificado do contêiner.
get_container_client

Obtenha um ContainerProxy para um contêiner com a ID especificada (nome).
get_throughput

Obtenha o objeto ThroughputProperties para este banco de dados.

Se nenhuma ThroughputProperties já existir para o banco de dados, uma exceção será gerada.
get_user_client

Obtenha um UserProxy para um usuário com a ID especificada.
list_containers

Liste os contêineres no banco de dados.
list_users

Liste todos os usuários no contêiner.
query_containers

Liste as propriedades para contêineres no banco de dados atual.
query_users

Retornar todos os usuários que correspondem à consulta fornecida.
read

Leia as propriedades do banco de dados.
replace_container

Redefina as propriedades do contêiner.

As alterações de propriedade são mantidas imediatamente. Todas as propriedades não especificadas serão redefinidas para seus valores padrão.
replace_throughput

Substitua a taxa de transferência no nível do banco de dados.

Se nenhuma ThroughputProperties já existir para o banco de dados, uma exceção será gerada.
replace_user

Substitui o usuário especificado se ele existir no contêiner.
upsert_user

Insira ou atualize o usuário especificado.

Se o usuário já existir no contêiner, ele será substituído. Se o usuário ainda não existir, ele será inserido.

create_container

Crie um novo contêiner com a ID fornecida (nome).

Se um contêiner com a ID fornecida já existir, um CosmosResourceExistsError será gerado.

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

Parâmetros

id
str
Obrigatório

ID (nome) do contêiner a ser criado.

partition_key
PartitionKey
Obrigatório

A chave de partição a ser usada para o contêiner.

indexing_policy
dict[str, str]

A política de indexação a ser aplicada ao contêiner.

default_ttl
int

TTL (tempo de vida padrão) para itens no contêiner. Se não for especificado, os itens não expirarão.

offer_throughput
Union[int, ThroughputProperties]

A taxa de transferência provisionada para esta oferta.

unique_key_policy
dict[str, str]

A política de chave exclusiva a ser aplicada ao contêiner.

conflict_resolution_policy
dict[str, str]

A política de resolução de conflitos a ser aplicada ao contêiner.

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.

analytical_storage_ttl
int

TTL (tempo de vida útil do repositório analítico) para itens no contêiner. Um valor none deixa o armazenamento analítico desativado e um valor de -1 ativa o armazenamento analítico sem TTL. Observe que o armazenamento analítico só pode ser habilitado em contas habilitadas Link do Synapse.

Retornos

Uma instância containerProxy que representa o novo contêiner.

Tipo de retorno

ContainerProxy

Exceções

CosmosHttpResponseError

Falha na criação do contêiner.

Exemplos

Crie um contêiner com configurações padrão:


           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 contêiner com configurações específicas; nesse 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 contêiner se ele ainda não existir.

Se o contêiner já existir, as configurações existentes serão retornadas. Observação: ele não marcar nem atualiza as configurações de contêiner existentes ou a taxa de transferência da oferta se forem diferentes do que foi passado para o método .

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

Parâmetros

id
str
Obrigatório

ID (nome) do contêiner a ser criado.

partition_key
PartitionKey
Obrigatório

A chave de partição a ser usada para o contêiner.

indexing_policy
dict[str, str]

A política de indexação a ser aplicada ao contêiner.

default_ttl
int

TTL (tempo de vida padrão) para itens no contêiner. Se não for especificado, os itens não expirarão.

offer_throughput
Union[int, ThroughputProperties]

A taxa de transferência provisionada para esta oferta.

unique_key_policy
dict[str, str]

A política de chave exclusiva a ser aplicada ao contêiner.

conflict_resolution_policy
dict[str, str]

A política de resolução de conflitos a ser aplicada ao contêiner.

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.

analytical_storage_ttl
int

TTL (tempo de vida útil do repositório analítico) para itens no contêiner. Um valor none deixa o armazenamento analítico desativado e um valor de -1 ativa o armazenamento analítico sem TTL. Observe que o armazenamento analítico só pode ser habilitado em contas habilitadas Link do Synapse.

Retornos

Uma instância containerProxy que representa o novo contêiner.

Tipo de retorno

ContainerProxy

Exceções

CosmosHttpResponseError

Falha na criação do contêiner.

create_user

Crie um novo usuário no contêiner.

Para atualizar ou substituir um usuário existente, use o <xref:ContainerProxy.upsert_user> método .

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

Parâmetros

body
Dict[str, Any]
Obrigatório

Um objeto semelhante a um ditado com uma chave de ID e um valor que representa o usuário a ser criado. A ID de usuário deve ser exclusiva no banco de dados e consistir em no máximo 255 caracteres.

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

Um callable invocado com os metadados de resposta.

Retornos

Uma instância do UserProxy que representa o novo usuário.

Tipo de retorno

UserProxy

Exceções

CosmosHttpResponseError

Se o usuário determinado não pôde ser criado.

Exemplos

Criar um usuário de banco 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

Excluir um contêiner.

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

Parâmetros

container
str ou Dict[str, Any] ou ContainerProxy
Obrigatório

A ID (nome) do contêiner a ser excluído. Você pode passar a ID do contêiner para excluir, uma ContainerProxy instância ou um ditado que representa as propriedades do contêiner.

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

Um callable invocado com os metadados de resposta.

Tipo de retorno

None

Exceções

CosmosHttpResponseError

Se o contêiner não puder ser excluído.

delete_user

Exclua o usuário especificado do contêiner.

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

Parâmetros

user
Union[str, Dict[str, Any], UserProxy]
Obrigatório

A ID (nome), ditado que representa as propriedades ou UserProxy a instância do usuário a ser excluído.

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

Um callable invocado com os metadados de resposta.

Tipo de retorno

None

Exceções

CosmosHttpResponseError

O usuário não foi excluído com êxito.

CosmosResourceNotFoundError

O usuário não existe no contêiner.

get_container_client

Obtenha um ContainerProxy para um contêiner com a ID especificada (nome).

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

Parâmetros

container
Union[str, Dict[str, Any], ContainerProxy]
Obrigatório

A ID (nome), dict que representa as propriedades ou ContainerProxy a instância do contêiner a ser obtido.

Retornos

Uma instância ContainerProxy que representa o contêiner.

Tipo de retorno

ContainerProxy

Exceções

CosmosHttpResponseError

Falha na criação do contêiner.

Exemplos

Obtenha um contêiner existente, tratando uma falha se encontrado:


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

get_throughput

Obtenha o objeto ThroughputProperties para este banco de dados.

Se nenhuma ThroughputProperties já existir para o banco de dados, uma exceção será gerada.

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.

Retornos

ThroughputProperties para o banco de dados.

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

Nenhuma propriedade de taxa de transferência existe para o banco de dados ou as propriedades de taxa de transferência não puderam ser recuperadas.

get_user_client

Obtenha um UserProxy para um usuário com a ID especificada.

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

Parâmetros

user
Union[str, Dict[str, Any], UserProxy]
Obrigatório

A ID (nome), ditado que representa as propriedades ou UserProxy a instância do usuário a ser obtido.

Retornos

Uma instância userProxy que representa o usuário recuperado.

Tipo de retorno

UserProxy

Exceções

CosmosHttpResponseError

Falha na criação do contêiner.

list_containers

Liste os contêineres no banco de dados.

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

Um callable invocado com os metadados de resposta.

Retornos

Um AsyncItemPaged de propriedades de contêiner (dicts).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

Falha na criação do contêiner.

Exemplos

Listar todos os contêineres no banco 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 usuários no contêiner.

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

Parâmetros

max_item_count
int

Número máximo de usuários a serem retornados 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.

Retornos

Um AsyncItemPaged de propriedades do usuário (dicts).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

Falha na criação do contêiner.

query_containers

Liste as propriedades para contêineres no banco 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 ser executada.

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

Um callable invocado com os metadados de resposta.

Retornos

Um AsyncItemPaged de propriedades de contêiner (dicts).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

Falha na criação do contêiner.

query_users

Retornar todos os usuários que correspondem à consulta fornecida.

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

Parâmetros

query
Union[str, Dict[str, Any]]
Obrigatório

A consulta SQL do Azure Cosmos DB a ser executada.

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 nenhuma consulta for fornecida.

max_item_count
int

Número máximo de usuários a serem retornados 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.

Retornos

Um AsyncItemPaged de propriedades do usuário (dicts).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

Falha na criação do contêiner.

read

Leia as propriedades do banco de dados.

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

Parâmetros

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

Um callable invocado com os metadados de resposta.

Retornos

Um dict que representa as propriedades do banco de dados

Tipo de retorno

Dict[str, Any]

Exceções

CosmosHttpResponseError

Se o banco de dados determinado não puder ser recuperado.

replace_container

Redefina as propriedades do contêiner.

As alterações de propriedade são mantidas imediatamente. Todas as propriedades não especificadas serão redefinidas para seus valores padrão.

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

Parâmetros

container
Union[str, Dict[str, Any], ContainerProxy]
Obrigatório

A ID (nome), dict que representa as propriedades ou ContainerProxy a instância do contêiner a ser substituído.

partition_key
PartitionKey
Obrigatório

A chave de partição a ser usada para o contêiner.

indexing_policy
dict[str, str]

A política de indexação a ser aplicada ao contêiner.

default_ttl
int

TTL (vida útil) padrão para itens no contêiner. Se não for especificado, os itens não expirarão.

conflict_resolution_policy
dict[str, str]

A política de resolução de conflitos a ser aplicada ao contêiner.

session_token
str

Token para uso com consistência de sessã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.

initial_headers
dict[str, str]

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

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

Um callable invocado com os metadados de resposta.

analytical_storage_ttl
int

TTL (vida útil do repositório analítico) para itens no contêiner. Um valor None deixa o armazenamento analítico desativado e um valor de -1 ativa o armazenamento analítico sem TTL. Observe que o armazenamento analítico só pode ser habilitado em Link do Synapse contas habilitadas.

Retornos

Uma instância ContainerProxy que representa o contêiner após a conclusão da substituição.

Tipo de retorno

ContainerProxy

Exceções

CosmosHttpResponseError

Gerado se o contêiner não puder ser substituído. Isso inclui se o contêiner com a ID fornecida não existir.

Exemplos

Redefina a propriedade TTL em um contêiner e exiba 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 a taxa de transferência no nível do banco de dados.

Se nenhuma ThroughputProperties já existir para o banco de dados, uma exceção será gerada.

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

Parâmetros

throughput
Union[int, ThroughputProperties]
Obrigatório

A taxa de transferência a ser definida.

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

Um callable invocado com os metadados de resposta.

Retornos

ThroughputProperties para o banco de dados, atualizado com nova taxa de transferência.

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

Nenhuma propriedade de taxa de transferência existe para o banco de dados ou as propriedades de taxa de transferência não puderam ser atualizadas.

replace_user

Substitui o usuário especificado se ele existir no contêiner.

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]
Obrigatório

A ID (nome), dict que representa as propriedades ou UserProxy a instância do usuário a ser substituído.

body
Dict[str, Any]
Obrigatório

Um objeto semelhante a um dict que representa o usuário a ser substituído.

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

Um callable invocado com os metadados de resposta.

Retornos

Uma instância userProxy que representa o usuário após a substituição.

Tipo de retorno

UserProxy

Exceções

CosmosHttpResponseError

Se a substituição falhar ou o usuário com determinada ID não existir.

upsert_user

Insira ou atualize o usuário especificado.

Se o usuário já existir no contêiner, ele será substituído. Se o usuário ainda não existir, ele será inserido.

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

Parâmetros

body
Dict[str, Any]
Obrigatório

Um objeto semelhante a um dict que representa o usuário a ser atualizado ou inserido.

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

Um callable invocado com os metadados de resposta.

Retornos

Uma instância userProxy que representa o usuário upserted.

Tipo de retorno

UserProxy

Exceções

CosmosHttpResponseError

Se o usuário determinado não pôde ser upserted.