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 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: 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 de utilizadores.
- Herança
-
builtins.objectDatabaseProxy
Construtor
DatabaseProxy(client_connection: CosmosClientConnection, id: str, properties: Dict[str, Any] = None)Parâmetros
- client_connection
- <xref:ClientSession>
Cliente a partir do qual esta base de dados foi obtida.
- properties
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. :gera ~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 |
Liste 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 correspondem à 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. :gera ~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, 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) -> ContainerProxyParâmetros
- id
ID (nome) do contentor a criar.
- partition_key
A chave de partição a utilizar para o contentor.
- indexing_policy
A política de indexação a aplicar ao contentor.
- default_ttl
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.>
O débito aprovisionado para esta oferta.
- unique_key_policy
A política de chave exclusiva a aplicar ao contentor.
- conflict_resolution_policy
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.
- 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) -> ContainerProxyParâmetros
- id
ID (nome) do contentor para ler ou criar.
- partition_key
A chave de partição a utilizar para o contentor.
- indexing_policy
A política de indexação a aplicar ao contentor.
- default_ttl
Tempo de vida predefinido (TTL) para itens no contentor. Se não for especificado, os itens não expiram.
- populate_query_metrics
Ative a devolução de métricas de consulta nos cabeçalhos de resposta.
- offer_throughput
O débito aprovisionado para esta oferta.
- unique_key_policy
A política de chave exclusiva a aplicar ao contentor.
- conflict_resolution_policy
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.
- 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) -> UserProxyParâmetros
- body
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) -> NoneParâmetros
- container
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.
- 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) -> NoneParâmetros
- user
O ID (nome), o ditado que representa as propriedades ou 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]) -> ContainerProxyParâmetros
- container
O ID (nome) do contentor, uma 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, manuseando 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. :gera ~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) -> ThroughputPropertiesTipo 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]) -> UserProxyParâmetros
- user
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 obtido.
Tipo de retorno
Exceções
A criação do contentor falhou.
list_containers
Liste 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
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.
- 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
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 do 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
A consulta SQL do Azure Cosmos DB a executar.
- parameters
Matriz opcional de parâmetros para a consulta. Ignorado se não for fornecida nenhuma consulta.
- max_item_count
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.
- 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 correspondem à 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
A consulta SQL do Azure Cosmos DB a executar.
- parameters
Matriz opcional de parâmetros para a consulta. Ignorado se não for fornecida nenhuma consulta.
- max_item_count
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 do 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.
- response_hook
- Callable
Um callable invocado com os metadados de resposta.
Tipo de retorno
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. :gera ~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) -> ThroughputPropertiesTipo 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) -> ContainerProxyParâmetros
- container
O ID (nome), o ditado que representa as propriedades ou ContainerProxy a instância do contentor a substituir.
- partition_key
A chave de partição a utilizar para o contentor.
- indexing_policy
A política de indexação a aplicar ao contentor.
- default_ttl
Time to live (TTL) predefinido para itens no contentor. Se não for especificado, os itens não expiram.
- conflict_resolution_policy
A política de resolução de conflitos a aplicar ao contentor.
- populate_query_metrics
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.
- response_hook
- Callable
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 contentor após a conclusão da substituição.
Tipo de retorno
Exceções
Gerado se o contentor não puder ser substituído. Isto inclui se o contentor com um determinado ID 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) -> ThroughputPropertiesParâmetros
- throughput
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 for 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) -> UserProxyParâmetros
- user
O ID (nome), o ditado que representa as propriedades ou UserProxy a instância do utilizador a substituir.
- body
Um objeto tipo dict 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, será substituído. Se o utilizador ainda não existir, é inserido.
upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxyParâmetros
- body
Um objeto tipo dict que representa o utilizador a 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 o utilizador especificado não puder ser upserted.
Azure SDK for Python
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários