ContainerProxy Classe

Referência

Uma interface para interagir com um contêiner de banco de dados específico.

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

Um contêiner em um banco de dados da API SQL do Azure Cosmos DB é uma coleção de documentos, cada um deles 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 padrão: None

Variáveis

id: str

ID (nome) do contêiner

session_token: str

O token de sessão para o contêiner.

Métodos

create_item	Crie um item no contêiner. Para atualizar ou substituir um item existente, use o upsert_item método .
delete_all_items_by_partition_key	O recurso de excluir por chave de partição é uma operação assíncrona em segundo plano que permite excluir todos os documentos com o mesmo valor de chave de partição lógica usando o SDK do Cosmos. A operação de exclusão por chave de partição é limitada a consumir no máximo 10% do total de RUs disponíveis no contêiner a cada segundo. Isso ajuda a limitar os recursos usados por essa tarefa em segundo plano.
delete_conflict	Exclua um conflito especificado do contêiner. Se o conflito ainda não existir no contêiner, uma exceção será gerada.
delete_item	Exclua o item especificado do contêiner. Se o item ainda não existir no contêiner, uma exceção será gerada.
get_conflict	Obtenha o conflito identificado pelo conflito.
get_throughput	Obtenha o objeto ThroughputProperties para esse contêiner. Se nenhuma ThroughputProperties já existir para o contêiner, uma exceção será gerada.
list_conflicts	Liste todos os conflitos no contêiner.
patch_item	Método provisório Corrige o item especificado com as operações fornecidas se ele existir no contêiner. Se o item ainda não existir no contêiner, uma exceção será gerada.
query_conflicts	Retornar todos os conflitos correspondentes a uma determinada consulta.
query_items	Retornar todos os resultados correspondentes à consulta fornecida. Você pode usar qualquer valor para o nome do contêiner na cláusula FROM, mas geralmente o nome do contêiner é usado. Nos exemplos abaixo, o nome do contêiner é "products" e é aliased como "p" para facilitar a referência na cláusula WHERE. token de continuação de resposta na resposta da consulta. Valores válidos são inteiros positivos. Um valor de 0 é o mesmo que não passar um valor (padrão sem limite). :palavra-chave int max_integrated_cache_staleness_in_ms: a desatualização máxima do cache para o cache integrado em Milissegundos. Para contas configuradas para usar o cache integrado, usando a Consistência de Sessão ou Eventual, é garantido que as respostas não sejam mais obsoletas do que esse valor.
query_items_change_feed	Obtenha uma lista classificada de itens que foram alterados, na ordem em que foram modificados.
read	Leia as propriedades do contêiner.
read_all_items	Liste todos os itens no contêiner.
read_item	Obtenha o item identificado pelo item.
replace_item	Substituirá o item especificado se ele existir no contêiner. Se o item ainda não existir no contêiner, uma exceção será gerada.
replace_throughput	Substitua a taxa de transferência do contêiner. Se nenhuma ThroughputProperties já existir para o contêiner, uma exceção será gerada.
upsert_item	Insira ou atualize o item especificado. Se o item já existir no contêiner, ele será substituído. Se o item ainda não existir, ele será inserido.

create_item

Crie um item no contêiner.

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

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

Parâmetros

body: dict[str, str]

Obrigatório

Um objeto semelhante a um dict que representa o item a ser criado.

pre_trigger_include: str

ID do gatilho a ser usada como gatilho de pré-operação.

post_trigger_include: str

ID de gatilho a ser usada como gatilho 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 Padrão, 1 para Excluir ou 2 para Incluir.

enable_automatic_id_generation: bool

Habilite a geração automática de IDs se nenhuma ID estiver presente.

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

Um callable invocado com os metadados de resposta.

Retornos

Um dict que representa o novo item.

Tipo de retorno

Dict[str, Any]

Exceções

CosmosHttpResponseError

O item com a ID fornecida já existe.

delete_all_items_by_partition_key

O recurso de excluir por chave de partição é uma operação assíncrona em segundo plano que permite excluir todos os documentos com o mesmo valor de chave de partição lógica usando o SDK do Cosmos. A operação de exclusão por chave de partição é limitada a consumir no máximo 10% do total de RUs disponíveis no contêiner a cada segundo. Isso ajuda a limitar os recursos usados por essa 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

Obrigatório

Chave de partição para os itens a serem excluídos.

pre_trigger_include: str

ID do gatilho a ser usada como gatilho de pré-operação.

post_trigger_include: str

ID de gatilho a ser usada como gatilho pós-operação.

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.

response_hook: Callable

Um callable invocado com os metadados de resposta.

Tipo de retorno

None

Exceções

CosmosHttpResponseError

O item com a ID fornecida já existe.

delete_conflict

Exclua um conflito especificado do contêiner.

Se o conflito ainda não existir no contêiner, uma exceção será gerada.

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

Obrigatório

A ID (nome) ou ditado que representa o conflito a ser recuperado.

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

Obrigatório

Chave de partição para o conflito a ser recuperado.

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 excluído com êxito.

CosmosResourceNotFoundError

O conflito não existe no contêiner.

delete_item

Exclua o item especificado do contêiner.

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

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

Obrigatório

A ID (nome) ou o dict que representa o item a ser excluído.

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

Obrigatório

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

pre_trigger_include: str

ID do gatilho a ser usada como gatilho de pré-operação.

post_trigger_include: str

ID de gatilho a ser usada como gatilho pós-operaçã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.

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[[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 excluído com êxito.

CosmosResourceNotFoundError

O item não existe no contêiner.

get_conflict

Obtenha o conflito identificado pelo 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]]

Obrigatório

A ID (nome) ou ditado que representa o conflito a ser recuperado.

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

Obrigatório

Chave de partição para o conflito a ser recuperado.

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

Um callable invocado com os metadados de resposta.

Retornos

Um dict que representa o conflito recuperado.

Tipo de retorno

Dict[str, Any]

Exceções

CosmosHttpResponseError

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

get_throughput

Obtenha o objeto ThroughputProperties para esse contêiner.

Se nenhuma ThroughputProperties já existir para o contêiner, uma exceção será gerada.

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.

Retornos

ThroughputProperties para o contêiner.

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

Nenhuma propriedade de taxa de transferência existe para o contêiner ou as propriedades de taxa de transferência não puderam ser recuperadas.

list_conflicts

Liste todos os conflitos no contêiner.

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

Parâmetros

max_item_count: int

Número máximo de itens a serem retornados 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.

Retornos

Um AsyncItemPaged de conflitos (dicts).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

O item com a ID fornecida já existe.

patch_item

Método provisório Corrige o item especificado com as operações fornecidas se ele existir no contêiner.

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

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

Obrigatório

A ID (nome) ou dict que representa o item a ser corrigido.

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

Obrigatório

A chave de partição do objeto a ser corrigido.

patch_operations: List[Dict[str, Any]]

Obrigatório

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

filter_predicate: str

filtro condicional a ser aplicado a operações de patch.

pre_trigger_include: str

ID do gatilho a ser usada como gatilho de pré-operação.

post_trigger_include: str

ID de gatilho a ser usada como gatilho pós-operação.

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.

response_hook: Callable

Um callable invocado com os metadados de resposta.

Retornos

Um dict que representa o item depois que as operações de patch foram concluídas.

Tipo de retorno

dict[str, Any]

Exceções

CosmosHttpResponseError

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

query_conflicts

Retornar 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]]

Obrigatório

A consulta SQL do Azure Cosmos DB a ser executada.

parameters: List[Dict[str, Any]]

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

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

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

max_item_count: int

Número máximo de itens a serem retornados 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.

Retornos

Um AsyncItemPaged de conflitos (dicts).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

O item com a ID fornecida já existe.

query_items

Retornar todos os resultados correspondentes à consulta fornecida.

Você pode usar qualquer valor para o nome do contêiner na cláusula FROM, mas geralmente o nome do contêiner é usado. Nos exemplos abaixo, o nome do contêiner é "products" e é aliased como "p" para facilitar a referência na cláusula WHERE.

token de continuação de resposta na resposta da consulta. Valores válidos são inteiros positivos. Um valor de 0 é o mesmo que não passar um valor (padrão sem limite). :palavra-chave int max_integrated_cache_staleness_in_ms: a desatualização máxima do cache para o cache integrado em

Milissegundos. Para contas configuradas para usar o cache integrado, usando a Consistência de Sessão ou Eventual, é garantido que as respostas não sejam mais obsoletas do que esse valor.

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

Retornos

Um AsyncItemPaged de itens (dicts).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

O item com a ID fornecida 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 classificada de itens que foram alterados, na 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 (true) ou do atual (false). Por padrão, ele é iniciado do atual (false).

partition_key_range_id: str

As solicitações do ChangeFeed podem ser executadas em intervalos de chaves de partição específicos. Isso é usado para processar o feed de alterações em paralelo entre vários consumidores.

continuation: str

e_tag valor a ser usado como continuação para leitura do feed de alterações.

max_item_count: int

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

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

chave de partição na qual as solicitações do ChangeFeed são direcionadas.

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

Um callable invocado com os metadados de resposta.

Retornos

Um AsyncItemPaged de itens (ditados).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

O item com a ID fornecida já existe.

read

Leia as propriedades do contêiner.

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

Parâmetros

populate_partition_key_range_statistics: bool

Habilite o retorno de estatísticas de intervalo de chaves de partição em cabeçalhos de resposta.

populate_quota_info: bool

Habilite o retorno de informações de cota de armazenamento de coleção em cabeçalhos de resposta.

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

Um callable invocado com os metadados de resposta.

Retornos

Dict que representa o contêiner recuperado.

Tipo de retorno

Dict[str, Any]

Exceções

CosmosHttpResponseError

Gerado se o contêiner não puder ser recuperado. Isso inclui se o contêiner não existir.

read_all_items

Liste todos os itens no contêiner.

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

Parâmetros

max_item_count: int

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[[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 desatualização máxima do cache para o cache integrado em milissegundos. Para contas configuradas para usar o cache integrado, usando a Consistência de Sessão ou Eventual, é garantido que as respostas não sejam mais obsoletas do que esse valor.

Retornos

Um AsyncItemPaged de itens (ditados).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

O item com a ID fornecida 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]]

Obrigatório

A ID (nome) ou ditado que representa o item a ser recuperado.

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

Obrigatório

Chave de partição para o item a ser recuperado.

post_trigger_include: str

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

Um callable invocado com os metadados de resposta.

max_integrated_cache_staleness_in_ms: int

Retornos

Dict que representa o item a ser recuperado.

Tipo de retorno

Dict[str, Any]

Exceções

CosmosHttpResponseError

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

Exemplos

Obtenha um item do banco de dados e atualize uma de suas propriedades:


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

replace_item

Substituirá o item especificado se ele existir no contêiner.

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

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

Obrigatório

A ID (nome) ou o ditado que representa o item a ser substituído.

body: Dict[str, Any]

Obrigatório

Um objeto semelhante a um ditado que representa o item a ser substituído.

pre_trigger_include: str

id de gatilho a ser usada como gatilho de pré-operação.

post_trigger_include: str

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

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

Um callable invocado com os metadados de resposta.

Retornos

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 com a ID fornecida não existe.

replace_throughput

Substitua a taxa de transferência do contêiner.

Se nenhuma ThroughputProperties já existir para o contêiner, uma exceção será gerada.

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

Parâmetros

throughput: Union[int, ThroughputProperties]

Obrigatório

A taxa de transferência a ser definida.

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

Um callable invocado com os metadados de resposta.

Retornos

ThroughputProperties para o contêiner, atualizado com nova taxa de transferência.

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

Nenhuma propriedade de taxa de transferência existe para o contêiner ou as propriedades de taxa de transferência não puderam ser atualizadas.

upsert_item

Insira ou atualize o item especificado.

Se o item já existir no contêiner, ele será substituído. Se o item ainda não existir, ele será inserido.

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

Parâmetros

body: Dict[str, Any]

Obrigatório

Um objeto semelhante a um ditado que representa o item a ser atualizado ou inserido.

pre_trigger_include: str

id de gatilho a ser usada como gatilho de pré-operação.

post_trigger_include: str

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

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

Um callable invocado com os metadados de resposta.

Retornos

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.

Compartilhar via

ContainerProxy Classe

Construtor

Parâmetros

Variáveis

Métodos

create_item

Parâmetros

Retornos

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

Retornos

Tipo de retorno

Exceções

get_throughput

Parâmetros

Retornos

Tipo de retorno

Exceções

list_conflicts

Parâmetros

Retornos

Tipo de retorno

Exceções

patch_item

Parâmetros

Retornos

Tipo de retorno

Exceções

query_conflicts

Parâmetros

Retornos

Tipo de retorno

Exceções

query_items

Retornos

Tipo de retorno

Exceções

Exemplos

query_items_change_feed

Parâmetros

Retornos

Tipo de retorno

Exceções

read

Parâmetros

Retornos

Tipo de retorno

Exceções

read_all_items

Parâmetros

Retornos

Tipo de retorno

Exceções

read_item

Parâmetros

Retornos

Tipo de retorno

Exceções

Exemplos

replace_item

Parâmetros

Retornos

Tipo de retorno

Exceções

replace_throughput