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

ContainerProxy

Exceções

CosmosHttpResponseError

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

Devoluções

Uma instância do ContainerProxy que representa o contentor.

Tipo de retorno

ContainerProxy

Exceções

CosmosHttpResponseError

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

UserProxy

Exceções

CosmosHttpResponseError

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

None

Exceções

CosmosHttpResponseError

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

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

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

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

ThroughputProperties

Exceções

CosmosHttpResponseError

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

UserProxy

Exceções

CosmosHttpResponseError

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

Iterable[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)
   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

Iterable[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(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

Iterable[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, 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

Iterable[str, Any]

Exceções

CosmosHttpResponseError

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

CosmosHttpResponseError

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

read_offer

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

read_offer(**kwargs: Any) -> ThroughputProperties

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

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

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

ThroughputProperties

Exceções

CosmosHttpResponseError

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

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.

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

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

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

Tipo de retorno

Exceções

read_offer

Tipo de retorno

Exceções

replace_container

Parâmetros

Devoluções

Tipo de retorno

Exceções

Exemplos

replace_throughput