Partilhar via


DatabaseProxy Classe

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

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: a etag de recursos necessária 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:ClientSession>
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 serão devolvidas. Nota: não verifica nem atualiza as definições de contentor existentes nem oferece débito se forem diferentes das que foram transmitidas 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. :keyword Callable response_hook: um callable invocado com os metadados de resposta. :returns: ThroughputProperties para a base de dados. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: não existem propriedades de débito para o contentor ou

não foi possível obter as propriedades de débito.

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.

read_offer

Obtenha o objeto ThroughputProperties para esta base de dados. Se ainda não existirem ThroughputProperties para a base de dados, é gerada uma exceção. :keyword Callable response_hook: um callable invocado com os metadados de resposta. :returns: ThroughputProperties para a base de dados. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: não existem propriedades de débito para o contentor ou

não foi possível obter as propriedades de débito.

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.

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.

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
Necessário

ID (nome) do contentor a criar.

partition_key
Necessário

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

indexing_policy
Necessário

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

default_ttl
Necessário

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

offer_throughput
int ou <xref:azure.cosmos.ThroughputProperties.>
Necessário

O débito aprovisionado para esta oferta.

unique_key_policy
Necessário

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

conflict_resolution_policy
Necessário

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

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 novo contentor.

Tipo de retorno

Exceções

A criação do contentor falhou.

Exemplos

Criar um contentor com predefinições:


   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 contentor com definições específicas; neste 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 contentor se ainda não existir.

Se o contentor já existir, as definições existentes serão devolvidas. Nota: não verifica nem atualiza as definições de contentor existentes nem oferece débito se forem diferentes das que foram transmitidas 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
Necessário

ID (nome) do contentor para ler ou criar.

partition_key
Necessário

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

indexing_policy
Necessário

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

default_ttl
Necessário

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

populate_query_metrics
Necessário

Ative a devolução de métricas de consulta nos cabeçalhos de resposta.

offer_throughput
Necessário

O débito aprovisionado para esta oferta.

unique_key_policy
Necessário

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

conflict_resolution_policy
Necessário

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

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.

Tipo de retorno

Exceções

Falha na leitura ou criação do contentor.

create_user

Crie um novo utilizador no contentor.

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

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

Parâmetros

body
Necessário

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

response_hook
Callable

Um callable invocado com os metadados de resposta.

Devoluções

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

Tipo de retorno

Exceções

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

Exemplos

Criar um utilizador de base 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

Eliminar um contentor.

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

Parâmetros

container
Necessário

O ID (nome) do contentor a eliminar. Pode transmitir o ID do contentor para eliminar, uma <xref:azure.cosmos.database.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

Um callable invocado com os metadados de resposta.

Tipo de retorno

Exceções

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

delete_user

Elimine o utilizador especificado do contentor.

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

Parâmetros

user
Necessário

O ID (nome), o ditado que representa as propriedades ou <xref:azure.cosmos.database.UserProxy> instâncias do utilizador a eliminar.

response_hook
Callable

Um callable invocado com os metadados de resposta.

Tipo de retorno

Exceções

O utilizador não foi eliminado com êxito.

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
Necessário

O ID (nome) do contentor, uma <xref:azure.cosmos.database.ContainerProxy> instância ou um ditado que representa as propriedades do contentor a obter.

Devoluções

Uma instância do ContainerProxy que representa a base de dados obtida.

Tipo de retorno

Exceções

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. :keyword Callable response_hook: um callable invocado com os metadados de resposta. :returns: ThroughputProperties para a base de dados. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: não existem propriedades de débito para o contentor ou

não foi possível obter as propriedades de débito.

get_throughput(**kwargs: Any) -> ThroughputProperties

Tipo de retorno

Exceções

A criação do contentor falhou.

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
Necessário

O ID (nome), o ditado que representa as propriedades ou <xref:azure.cosmos.database.UserProxy> instâncias do utilizador a obter.

Devoluções

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

Tipo de retorno

Exceções

A criação do contentor falhou.

list_containers

Listar os contentores na base 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
Necessário

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

Um callable invocado com os metadados de resposta.

Devoluções

Iterável de propriedades de contentor (dicts).

Tipo de retorno

Exceções

A criação do contentor falhou.

Exemplos

Listar todos os contentores na base 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 utilizadores no contentor.

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

Parâmetros

max_item_count
Necessário

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

response_hook
Callable

Um callable invocado com os metadados de resposta.

Devoluções

Iterável de propriedades de utilizador (dicts).

Tipo de retorno

Exceções

A criação do contentor falhou.

query_containers

Liste as propriedades dos contentores na base 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
Necessário

A consulta SQL do Azure Cosmos DB a executar.

parameters
Necessário

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

max_item_count
Necessário

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

Um callable invocado com os metadados de resposta.

Devoluções

Iterável de propriedades de contentor (dicts).

Tipo de retorno

Exceções

A criação do contentor falhou.

query_users

Devolver todos os utilizadores que correspondam à consulta especificada.

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

Parâmetros

query
Necessário

A consulta SQL do Azure Cosmos DB a executar.

parameters
Necessário

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

max_item_count
Necessário

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

response_hook
Callable

Um callable invocado com os metadados de resposta.

Devoluções

Iterável de propriedades de utilizador (dicts).

Tipo de retorno

Exceções

A criação do contentor falhou.

read

Leia as propriedades da base de dados.

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

Um callable invocado com os metadados de resposta.

Tipo de retorno

Dict[<xref:Str>, Any]

Exceções

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

read_offer

Obtenha o objeto ThroughputProperties para esta base de dados. Se ainda não existirem ThroughputProperties para a base de dados, é gerada uma exceção. :keyword Callable response_hook: um callable invocado com os metadados de resposta. :returns: ThroughputProperties para a base de dados. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: não existem propriedades de débito para o contentor ou

não foi possível obter as propriedades de débito.

read_offer(**kwargs: Any) -> ThroughputProperties

Tipo de retorno

Exceções

A criação do contentor falhou.

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_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
Necessário

O ID (nome), o ditado que representa as propriedades ou <xref:azure.cosmos.database.ContainerProxy> instâncias do contentor a substituir.

partition_key
Necessário

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

indexing_policy
Necessário

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

default_ttl
Necessário

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

conflict_resolution_policy
Necessário

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

populate_query_metrics
Necessário

Ative a devolução de métricas de consulta nos cabeçalhos de resposta.

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

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

Exceções

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)
   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 o débito ao nível da base de dados.

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

Parâmetros

throughput
Necessário

O débito a definir (um número inteiro).

response_hook
Callable

Um callable invocado com os metadados de resposta.

Devoluções

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

Tipo de retorno

Exceções

Se não existirem propriedades de débito para a base de dados ou se não foi possível atualizar as propriedades de débito.

replace_user

Substitui o utilizador especificado se existir no contentor.

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

Parâmetros

user
Necessário

O ID (nome), o ditado que representa as propriedades ou <xref:azure.cosmos.database.UserProxy> instâncias do utilizador a substituir.

body
Necessário

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

response_hook
Callable

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

Exceções

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.

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

Parâmetros

body
Necessário

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

response_hook
Callable

Um callable invocado com os metadados de resposta.

Devoluções

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

Tipo de retorno

Exceções

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