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 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 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: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 que correspondem à 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

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.

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

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 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 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 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 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), dict que representa as propriedades ou UserProxy a instância do usuário a ser recuperado.

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(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 que correspondem à 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 determinado não puder ser recuperado.

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.

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), dict que representa as propriedades ou 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 (vida útil) 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

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

Substitui 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), dict que representa as propriedades ou UserProxy a instância do usuário a ser substituído.

body
Obrigatório

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

response_hook
Callable

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.

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

Parâmetros

body
Obrigatório

Um objeto semelhante a um dict 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 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.