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:CosmosClient.get_database_client> método .

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 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 SQL do Azure Cosmos DB tem as seguintes propriedades geradas pelo sistema. 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:ClientSession>

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. :palavra-chave response_hook callable: um callable invocado com os metadados de resposta. :returns: ThroughputProperties para o banco de dados. :gera ~azure.cosmos.exceptions.CosmosHttpResponseError: não existem propriedades de taxa de transferência para o contêiner 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.
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 correspondentes à consulta fornecida.
read	Leia as propriedades do banco de dados.
read_offer	Obtenha o objeto ThroughputProperties para este banco de dados. Se nenhuma ThroughputProperties já existir para o banco de dados, uma exceção será gerada. :palavra-chave response_hook callable: um callable invocado com os metadados de resposta. :returns: ThroughputProperties para o banco de dados. :gera ~azure.cosmos.exceptions.CosmosHttpResponseError: não existem propriedades de taxa de transferência para o contêiner ou as propriedades de taxa de transferência não puderam ser recuperadas.
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.
replace_user	Substituirá 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.

create_container(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

Parâmetros

id

Obrigatório

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

partition_key

Obrigatório

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

indexing_policy

Obrigatório

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

default_ttl

Obrigatório

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

offer_throughput: int ou <xref:azure.cosmos.ThroughputProperties.>

Obrigatório

A taxa de transferência provisionada para esta oferta.

unique_key_policy

Obrigatório

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

conflict_resolution_policy

Obrigatório

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

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

create_container_if_not_exists(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

Parâmetros

id

Obrigatório

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

partition_key

Obrigatório

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

indexing_policy

Obrigatório

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

default_ttl

Obrigatório

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

populate_query_metrics

Obrigatório

Habilite o retorno de métricas de consulta em cabeçalhos de resposta.

offer_throughput

Obrigatório

A taxa de transferência provisionada para esta oferta.

unique_key_policy

Obrigatório

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

conflict_resolution_policy

Obrigatório

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

Um callable invocado com os metadados de resposta.

analytical_storage_ttl: int

Retornos

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

Tipo de retorno

ContainerProxy

Exceções

CosmosHttpResponseError

Falha na leitura ou 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 .

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

Parâmetros

body

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

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:
       database.create_user(dict(id="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.

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

Parâmetros

container

Obrigatório

A ID (nome) do contêiner a ser excluído. Você pode passar a ID do contêiner para excluir, uma <xref:azure.cosmos.database.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

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.

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

Parâmetros

user

Obrigatório

A ID (nome), ditado que representa as propriedades ou <xref:azure.cosmos.database.UserProxy> a instância do usuário a ser excluído.

response_hook: Callable

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

Obrigatório

A ID (nome) do contêiner, uma <xref:azure.cosmos.database.ContainerProxy> instância ou um ditado que representa as propriedades do contêiner a ser recuperado.

Retornos

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

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. :palavra-chave response_hook callable: um callable invocado com os metadados de resposta. :returns: ThroughputProperties para o banco de dados. :gera ~azure.cosmos.exceptions.CosmosHttpResponseError: não existem propriedades de taxa de transferência para o contêiner ou

as propriedades de taxa de transferência não puderam ser recuperadas.

get_throughput(**kwargs: Any) -> ThroughputProperties

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

Falha na criação do contêiner.

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

Obrigatório

A ID (nome), ditado que representa as propriedades ou <xref:azure.cosmos.database.UserProxy> a instância do usuário a ser recuperado.

Retornos

Uma instância do 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(max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parâmetros

max_item_count

Obrigatório

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

Um callable invocado com os metadados de resposta.

Retornos

Um Iterável de propriedades de contêiner (dicts).

Tipo de retorno

Iterable[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)
   for container in database.list_containers():
       print("Container ID: {}".format(container['id']))

list_users

Liste todos os usuários no contêiner.

list_users(max_item_count: int | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parâmetros

max_item_count

Obrigatório

Número máximo de usuários a serem retornados na operação de enumeração.

response_hook: Callable

Um callable invocado com os metadados de resposta.

Retornos

Um Iterável de propriedades do usuário (dicts).

Tipo de retorno

Iterable[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(query: str | None = None, parameters: List[str] | None = None, max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parâmetros

query

Obrigatório

A consulta SQL do Azure Cosmos DB a ser executada.

parameters

Obrigatório

Matriz opcional de parâmetros para a consulta. Ignorado se nenhuma consulta for fornecida.

max_item_count

Obrigatório

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

Um callable invocado com os metadados de resposta.

Retornos

Um Iterável de propriedades de contêiner (dicts).

Tipo de retorno

Iterable[dict[str, Any]]

Exceções

CosmosHttpResponseError

Falha na criação do contêiner.

query_users

Retornar todos os usuários correspondentes à consulta fornecida.

query_users(query: str, parameters: List[str] | None = None, max_item_count: int | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parâmetros

query

Obrigatório

A consulta SQL do Azure Cosmos DB a ser executada.

parameters

Obrigatório

Matriz opcional de parâmetros para a consulta. Ignorado se nenhuma consulta for fornecida.

max_item_count

Obrigatório

Número máximo de usuários a serem retornados na operação de enumeração.

response_hook: Callable

Um callable invocado com os metadados de resposta.

Retornos

Um Iterável de propriedades do usuário (dicts).

Tipo de retorno

Iterable[str, Any]

Exceções

CosmosHttpResponseError

Falha na criação do contêiner.

read

Leia as propriedades do banco de dados.

read(populate_query_metrics: bool | None = None, **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

Um callable invocado com os metadados de resposta.

Tipo de retorno

Dict[<xref:Str>, Any]

Exceções

CosmosHttpResponseError

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

read_offer

as propriedades de taxa de transferência não puderam ser recuperadas.

read_offer(**kwargs: Any) -> ThroughputProperties

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

Falha na criação do contêiner.

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_container(container: str | ContainerProxy | Dict[str, Any], partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> ContainerProxy

Parâmetros

container

Obrigatório

A ID (nome), ditado que representa as propriedades ou <xref:azure.cosmos.database.ContainerProxy> a instância do contêiner a ser substituído.

partition_key

Obrigatório

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

indexing_policy

Obrigatório

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

default_ttl

Obrigatório

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

conflict_resolution_policy

Obrigatório

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

populate_query_metrics

Obrigatório

Habilite o retorno de métricas de consulta em cabeçalhos de resposta.

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

Um callable invocado com os metadados de resposta.

analytical_storage_ttl: int

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)
   database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)

   # Display the new TTL setting for the container
   container_props = 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.

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

Parâmetros

throughput

Obrigatório

A taxa de transferência a ser definida (um inteiro).

response_hook: Callable

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

Se nenhuma propriedade de taxa de transferência existir para o banco de dados ou se as propriedades de taxa de transferência não puderem ser atualizadas.

replace_user

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

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

Parâmetros

user

Obrigatório

A ID (nome), ditado que representa as propriedades ou <xref:azure.cosmos.database.UserProxy> a instância do usuário a ser substituído.

body

Obrigatório

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

response_hook: Callable

Um callable invocado com os metadados de resposta.

Retornos

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

Tipo de retorno

UserProxy

Exceções

CosmosHttpResponseError

Se a substituição falhou 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.

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

Parâmetros

body

Obrigatório

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

response_hook: Callable

Um callable invocado com os metadados de resposta.

Retornos

Uma instância do 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.

Compartilhar via

DatabaseProxy Classe

Construtor

Parâmetros

Variáveis

Métodos

create_container

Parâmetros

Retornos

Tipo de retorno

Exceções

Exemplos

create_container_if_not_exists

Parâmetros

Retornos

Tipo de retorno

Exceções

create_user

Parâmetros

Retornos

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

Retornos

Tipo de retorno

Exceções

Exemplos

get_throughput

Tipo de retorno

Exceções

get_user_client

Parâmetros

Retornos

Tipo de retorno

Exceções

list_containers

Parâmetros

Retornos

Tipo de retorno

Exceções

Exemplos

list_users

Parâmetros

Retornos

Tipo de retorno

Exceções

query_containers

Parâmetros

Retornos

Tipo de retorno

Exceções

query_users

Parâmetros

Retornos

Tipo de retorno

Exceções

read

Parâmetros

Tipo de retorno

Exceções

read_offer

Tipo de retorno

Exceções

replace_container

Parâmetros

Retornos

Tipo de retorno

Exceções

Exemplos

replace_throughput