ContainerProxy Classe

Referência

Uma interface para interagir com um Contentor de BD específico.

Esta classe não deve ser instanciada diretamente. Em vez disso, utilize o <xref:azure.cosmos.aio.database.DatabaseProxy.get_container_client> método para obter um contentor existente ou o <xref:azure.cosmos.aio.database.DatabaseProxy.create_container> método para criar um novo contentor.

Um contentor numa base de dados da API SQL do Azure Cosmos DB é uma coleção de documentos, cada um dos quais é representado como um Item.

Herança: builtins.object

ContainerProxy

Construtor

ContainerProxy(client_connection: CosmosClientConnection, database_link: str, id: str, properties: Dict[str, Any] = None)

Parâmetros

client_connection

database_link

id

properties

valor predefinido: None

Variáveis

id: str

ID (nome) do contentor

session_token: str

O token de sessão do contentor.

Métodos

create_item	Crie um item no contentor. Para atualizar ou substituir um item existente, utilize o upsert_item método .
delete_all_items_by_partition_key	A funcionalidade eliminar por chave de partição é uma operação assíncrona em segundo plano que lhe permite eliminar todos os documentos com o mesmo valor de chave de partição lógica com o SDK do Cosmos. A operação eliminar por chave de partição está limitada a consumir, no máximo, 10% do total de RU/s disponíveis no contentor a cada segundo. Isto ajuda a limitar os recursos utilizados por esta tarefa em segundo plano.
delete_conflict	Elimine um conflito especificado do contentor. Se o conflito ainda não existir no contentor, é gerada uma exceção.
delete_item	Elimine o item especificado do contentor. Se o item ainda não existir no contentor, será gerada uma exceção.
get_conflict	Obtenha o conflito identificado por conflito.
get_throughput	Obtenha o objeto ThroughputProperties para este contentor. Se ainda não existirem ThroughputProperties para o contentor, é gerada uma exceção.
list_conflicts	Liste todos os conflitos no contentor.
patch_item	Método provisório Corrige o item especificado com as operações fornecidas, se existir no contentor. Se o item ainda não existir no contentor, será gerada uma exceção.
query_conflicts	Devolver todos os conflitos correspondentes a uma determinada consulta.
query_items	Devolver todos os resultados correspondentes à consulta especificada. Pode utilizar qualquer valor para o nome do contentor na cláusula FROM, mas, muitas vezes, o nome do contentor é utilizado. Nos exemplos abaixo, o nome do contentor é "produtos" e é aliasado como "p" para uma referência mais fácil na cláusula WHERE. token de continuação de resposta na resposta da consulta. Os valores válidos são números inteiros positivos. Um valor de 0 é o mesmo que não transmitir um valor (predefinição sem limite). :keyword int max_integrated_cache_staleness_in_ms: A estagnação máxima da cache para a cache integrada no milissegundos. Para contas configuradas para utilizar a cache integrada, através da consistência Sessão ou Eventual, é garantido que as respostas não são mais obsoletas do que este valor.
query_items_change_feed	Obtenha uma lista ordenada de itens que foram alterados pela ordem em que foram modificados.
read	Leia as propriedades do contentor.
read_all_items	Liste todos os itens no contentor.
read_item	Obtenha o item identificado pelo item.
replace_item	Substitui o item especificado se existir no contentor. Se o item ainda não existir no contentor, será gerada uma exceção.
replace_throughput	Substitua o débito do contentor. Se ainda não existirem ThroughputProperties para o contentor, é gerada uma exceção.
upsert_item	Insira ou atualize o item especificado. Se o item já existir no contentor, será substituído. Se o item ainda não existir, é inserido.

create_item

Crie um item no contentor.

Para atualizar ou substituir um item existente, utilize o upsert_item método .

async create_item(body: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]

Parâmetros

body: dict[str, str]

Necessário

Um objeto tipo dict que representa o item a criar.

pre_trigger_include: str

ID do acionador a ser utilizado como acionador de pré-operação.

post_trigger_include: str

ID do acionador a ser utilizado como acionador pós-operação.

indexing_directive: Union[int, IndexingDirective]

Enumera os valores possíveis para indicar se o documento deve ser omitido da indexação. Os valores possíveis incluem: 0 para Predefinição, 1 para Excluir ou 2 para Incluir.

enable_automatic_id_generation: bool

Ative a geração automática de IDs se não existir nenhum ID.

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[[Dict[str, str], Dict[str, Any]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Um ditado que representa o novo item.

Tipo de retorno

Dict[str, Any]

Exceções

CosmosHttpResponseError

O item com o ID especificado já existe.

delete_all_items_by_partition_key

A funcionalidade eliminar por chave de partição é uma operação assíncrona em segundo plano que lhe permite eliminar todos os documentos com o mesmo valor de chave de partição lógica com o SDK do Cosmos. A operação eliminar por chave de partição está limitada a consumir, no máximo, 10% do total de RU/s disponíveis no contentor a cada segundo. Isto ajuda a limitar os recursos utilizados por esta tarefa em segundo plano.

async delete_all_items_by_partition_key(partition_key: str | int | float | bool, **kwargs: Any) -> None

Parâmetros

partition_key: Any

Necessário

Chave de partição para os itens a serem eliminados.

pre_trigger_include: str

ID do acionador a ser utilizado como acionador de pré-operação.

post_trigger_include: str

ID do acionador a ser utilizado como acionador pós-operação.

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

None

Exceções

CosmosHttpResponseError

O item com o ID especificado já existe.

delete_conflict

Elimine um conflito especificado do contentor.

Se o conflito ainda não existir no contentor, é gerada uma exceção.

async delete_conflict(conflict: str | Dict[str, Any], partition_key: str | int | float | bool, **kwargs: Any) -> None

Parâmetros

conflict: Union[str, Dict[str, Any]]

Necessário

O ID (nome) ou o ditado que representa o conflito a obter.

partition_key: Union[str, int, float, bool]

Necessário

Chave de partição do conflito a obter.

response_hook: Callable[[Dict[str, str], None], None]

Um callable invocado com os metadados de resposta.

Tipo de retorno

None

Exceções

CosmosHttpResponseError

O conflito não foi eliminado com êxito.

CosmosResourceNotFoundError

O conflito não existe no contentor.

delete_item

Elimine o item especificado do contentor.

Se o item ainda não existir no contentor, será gerada uma exceção.

async delete_item(item: str | Dict[str, Any], partition_key: str | int | float | bool, **kwargs: Any) -> None

Parâmetros

item: Union[str, Dict[str, Any]]

Necessário

O ID (nome) ou o item que representa a eliminação.

partition_key: Union[str, int, float, bool]

Necessário

Especifica o valor da chave de partição para o item.

pre_trigger_include: str

ID do acionador a ser utilizado como acionador de pré-operação.

post_trigger_include: str

ID do acionador a ser utilizado como acionador pós-operaçã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.

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[[Dict[str, str], None], None]

Um callable invocado com os metadados de resposta.

Tipo de retorno

None

Exceções

CosmosHttpResponseError

O item não foi eliminado com êxito.

CosmosResourceNotFoundError

O item não existe no contentor.

get_conflict

Obtenha o conflito identificado por conflito.

async get_conflict(conflict: str | Dict[str, Any], partition_key: str | int | float | bool, **kwargs: Any) -> Dict[str, Any]

Parâmetros

conflict: Union[str, Dict[str, Any]]

Necessário

O ID (nome) ou o ditado que representa o conflito a obter.

partition_key: Union[str, int, float, bool]

Necessário

Chave de partição do conflito a obter.

response_hook: Callable[[Dict[str, str], Dict[str, Any]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Um ditado que representa o conflito obtido.

Tipo de retorno

Dict[str, Any]

Exceções

CosmosHttpResponseError

Não foi possível obter o conflito especificado.

get_throughput

Obtenha o objeto ThroughputProperties para este contentor.

Se ainda não existirem ThroughputProperties para o contentor, é gerada uma exceção.

async get_throughput(**kwargs: Any) -> ThroughputProperties

Parâmetros

response_hook: Callable[[Dict[str, str], List[Dict[str, Any]]], None]

Um callable invocado com os metadados de resposta.

Devoluções

ThroughputProperties para o contentor.

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

Não existem propriedades de débito para o contentor ou não foi possível obter as propriedades de débito.

list_conflicts

Liste todos os conflitos no contentor.

list_conflicts(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parâmetros

max_item_count: int

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

response_hook: Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Um AsyncItemPaged de conflitos (dicts).

Tipo de retorno

<xref:AsyncItemPaged>[Dict[str, Any]]

Exceções

CosmosHttpResponseError

O item com o ID especificado já existe.

patch_item

Método provisório Corrige o item especificado com as operações fornecidas, se existir no contentor.

Se o item ainda não existir no contentor, será gerada uma exceção.

async patch_item(item: str | Dict[str, Any], partition_key: str | int | float | bool, patch_operations: List[Dict[str, Any]], **kwargs: Any) -> Dict[str, Any]

Parâmetros

item: Union[str, Dict[str, Any]]

Necessário

O ID (nome) ou o ditado que representa o item a ser corrigido.

partition_key: Union[str, int, float, bool]

Necessário

A chave de partição do objeto a aplicar patch.

patch_operations: List[Dict[str, Any]]

Necessário

A lista de operações de patch a aplicar ao item.

filter_predicate: str

filtro condicional a aplicar às operações de Patch.

pre_trigger_include: str

ID do acionador a ser utilizado como acionador de pré-operação.

post_trigger_include: str

ID do acionador a ser utilizado como acionador pós-operação.

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.

Devoluções

Um ditado que representa o item após a passagem das operações de patch.

Tipo de retorno

dict[str, Any]

Exceções

CosmosHttpResponseError

As operações de patch falharam ou o item com o ID especificado não existe.

query_conflicts

Devolver todos os conflitos correspondentes a uma determinada consulta.

query_conflicts(query: str | Dict[str, Any], **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parâmetros

query: Union[str, Dict[str, Any]]

Necessário

A consulta SQL do Azure Cosmos DB a executar.

parameters: List[Dict[str, Any]]

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

partition_key: Union[str, int, float, bool]

Especifica o valor da chave de partição para o item. Se não for transmitida nenhuma, será executada uma consulta entre partições.

max_item_count: int

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

response_hook: Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Um AsyncItemPaged de conflitos (dicts).

Tipo de retorno

<xref:AsyncItemPaged>[Dict[str, Any]]

Exceções

CosmosHttpResponseError

O item com o ID especificado já existe.

query_items

Devolver todos os resultados correspondentes à consulta especificada.

Pode utilizar qualquer valor para o nome do contentor na cláusula FROM, mas, muitas vezes, o nome do contentor é utilizado. Nos exemplos abaixo, o nome do contentor é "produtos" e é aliasado como "p" para uma referência mais fácil na cláusula WHERE.

token de continuação de resposta na resposta da consulta. Os valores válidos são números inteiros positivos. Um valor de 0 é o mesmo que não transmitir um valor (predefinição sem limite). :keyword int max_integrated_cache_staleness_in_ms: A estagnação máxima da cache para a cache integrada no

milissegundos. Para contas configuradas para utilizar a cache integrada, através da consistência Sessão ou Eventual, é garantido que as respostas não são mais obsoletas do que este valor.

query_items(query: str | Dict[str, Any], **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Devoluções

Um AsyncItemPaged de itens (dicts).

Tipo de retorno

<xref:AsyncItemPaged>[Dict[str, Any]]

Exceções

CosmosHttpResponseError

O item com o ID especificado já existe.

Exemplos

Obtenha todos os produtos que não foram descontinuados:


           import json

           async for item in container.query_items(
                   query='SELECT * FROM products p WHERE p.productModel <> "DISCONTINUED"'
           ):
               print(json.dumps(item, indent=True))

Consulta parametrizada para obter todos os produtos que foram descontinuados:


           discontinued_items = container.query_items(
               query='SELECT * FROM products p WHERE p.productModel = @model AND p.productName="Widget"',
               parameters=[dict(name="@model", value="DISCONTINUED")],
           )
           async for item in discontinued_items:
               print(json.dumps(item, indent=True))

query_items_change_feed

Obtenha uma lista ordenada de itens que foram alterados pela ordem em que foram modificados.

query_items_change_feed(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parâmetros

is_start_from_beginning: bool

Obtenha se o feed de alterações deve começar do início (verdadeiro) ou do atual (falso). Por predefinição, começa a partir do atual (falso).

partition_key_range_id: str

Os pedidos do ChangeFeed podem ser executados em intervalos de chaves de partição específicos. Isto é utilizado para processar o feed de alterações em paralelo em vários consumidores.

continuation: str

e_tag valor a ser utilizado como continuação para ler o feed de alterações.

max_item_count: int

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

partition_key: Union[str, int, float, bool]

chave de partição na qual os pedidos do ChangeFeed são direcionados.

response_hook: Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Um AsyncItemPaged de itens (dicts).

Tipo de retorno

<xref:AsyncItemPaged>[Dict[str, Any]]

Exceções

CosmosHttpResponseError

O item com o ID especificado já existe.

read

Leia as propriedades do contentor.

async read(**kwargs: Any) -> Dict[str, Any]

Parâmetros

populate_partition_key_range_statistics: bool

Ative a devolução de estatísticas do intervalo de chaves de partição nos cabeçalhos de resposta.

populate_quota_info: bool

Ative a devolução de informações de quota de armazenamento de coleção nos cabeçalhos de resposta.

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[[Dict[str, str], Dict[str, Any]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Dict representando o contentor obtido.

Tipo de retorno

Dict[str, Any]

Exceções

CosmosHttpResponseError

Gerado se não for possível obter o contentor. Isto inclui se o contentor não existir.

read_all_items

Liste todos os itens no contentor.

read_all_items(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parâmetros

max_item_count: int

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[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Um callable invocado com os metadados de resposta.

max_integrated_cache_staleness_in_ms: int

A estagnação máxima da cache para a cache integrada em milissegundos. Para contas configuradas para utilizar a cache integrada, através da consistência Sessão ou Eventual, é garantido que as respostas não são mais obsoletas do que este valor.

Devoluções

Um AsyncItemPaged de itens (dicts).

Tipo de retorno

<xref:AsyncItemPaged>[Dict[str, Any]]

Exceções

CosmosHttpResponseError

O item com o ID especificado já existe.

read_item

Obtenha o item identificado pelo item.

async read_item(item: str | Dict[str, Any], partition_key: str | int | float | bool, **kwargs: Any) -> Dict[str, Any]

Parâmetros

item: Union[str, Dict[str, Any]]

Necessário

O ID (nome) ou o item que representa o item a obter.

partition_key: Union[str, int, float, bool]

Necessário

Chave de partição para o item a obter.

post_trigger_include: str

ID do acionador a ser utilizado como acionador pós-operaçã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[[Dict[str, str], Dict[str, Any]], None]

Um callable invocado com os metadados de resposta.

max_integrated_cache_staleness_in_ms: int

Devoluções

Dict representando o item a obter.

Tipo de retorno

Dict[str, Any]

Exceções

CosmosHttpResponseError

Não foi possível obter o item especificado.

Exemplos

Obtenha um item da base de dados e atualize uma das respetivas propriedades:


           item = await container.read_item("item2", partition_key="Widget")
           item["productModel"] = "DISCONTINUED"
           updated_item = await container.upsert_item(item)

replace_item

Substitui o item especificado se existir no contentor.

Se o item ainda não existir no contentor, será gerada uma exceção.

async replace_item(item: str | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]

Parâmetros

item: Union[str, Dict[str, Any]]

Necessário

O ID (nome) ou o ditado que representa o item a substituir.

body: Dict[str, Any]

Necessário

Um objeto tipo dict que representa o item a substituir.

pre_trigger_include: str

ID do acionador a ser utilizado como acionador de pré-operação.

post_trigger_include: str

ID do acionador a ser utilizado como acionador pós-operaçã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.

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[[Dict[str, str], Dict[str, Any]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Um ditado que representa o item após a substituição.

Tipo de retorno

Dict[str, Any]

Exceções

CosmosHttpResponseError

A substituição falhou ou o item pelo ID especificado não existe.

replace_throughput

Substitua o débito do contentor.

Se ainda não existirem ThroughputProperties para o contentor, é gerada uma exceção.

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

Parâmetros

throughput: Union[int, ThroughputProperties]

Necessário

O débito a definir.

response_hook: Callable[[Dict[str, str], Dict[str, Any]], None]

Um callable invocado com os metadados de resposta.

Devoluções

ThroughputProperties para o contentor, atualizado com novo débito.

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

Não existem propriedades de débito para o contentor ou não foi possível atualizar as propriedades de débito.

upsert_item

Insira ou atualize o item especificado.

Se o item já existir no contentor, será substituído. Se o item ainda não existir, é inserido.

async upsert_item(body: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]

Parâmetros

body: Dict[str, Any]

Necessário

Um objeto tipo dict que representa o item a atualizar ou inserir.

pre_trigger_include: str

ID do acionador a ser utilizado como acionador de pré-operação.

post_trigger_include: str

ID do acionador a ser utilizado como acionador pós-operaçã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.

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[[Dict[str, str], Dict[str, Any]], None]

Um callable invocado com os metadados de resposta.

Devoluções

Um ditado que representa o item upserted.

Tipo de retorno

Dict[str, Any]

Exceções

CosmosHttpResponseError

Não foi possível inserir o item especificado.

Partilhar via

ContainerProxy Classe

Construtor

Parâmetros

Variáveis

Métodos

create_item

Parâmetros

Devoluções

Tipo de retorno

Exceções

delete_all_items_by_partition_key

Parâmetros

Tipo de retorno

Exceções

delete_conflict

Parâmetros

Tipo de retorno

Exceções

delete_item

Parâmetros

Tipo de retorno

Exceções

get_conflict

Parâmetros

Devoluções

Tipo de retorno

Exceções

get_throughput

Parâmetros

Devoluções

Tipo de retorno

Exceções

list_conflicts

Parâmetros

Devoluções

Tipo de retorno

Exceções

patch_item

Parâmetros

Devoluções

Tipo de retorno

Exceções

query_conflicts

Parâmetros

Devoluções

Tipo de retorno

Exceções

query_items

Devoluções

Tipo de retorno

Exceções

Exemplos

query_items_change_feed

Parâmetros

Devoluções

Tipo de retorno

Exceções

read

Parâmetros

Devoluções

Tipo de retorno

Exceções

read_all_items

Parâmetros

Devoluções

Tipo de retorno

Exceções

read_item

Parâmetros

Devoluções

Tipo de retorno

Exceções

Exemplos

replace_item

Parâmetros

Devoluções

Tipo de retorno

Exceções

replace_throughput