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 get_container_client método para obter um contêiner existente ou o 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 este contêiner. Se nenhuma ThroughputProperties já existir para o contêiner, uma exceção será gerada. :palavra-chave response_hook callable: um callable invocado com os metadados de resposta. :returns: taxa de transferência para o contêiner. :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.
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 é chamado de "p" para facilitar a referência na cláusula WHERE. token de continuação de resposta na resposta da consulta. Os 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, as respostas têm a garantia de não serem 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	Obter o item identificado por item.
read_offer	Obtenha o objeto ThroughputProperties para esse contêiner. Se nenhuma ThroughputProperties já existir para o contêiner, uma exceção será gerada. :palavra-chave response_hook callable: um callable invocado com os metadados de resposta. :returns: taxa de transferência para o contêiner. :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_item	Substitui 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 .

create_item(body: Dict[str, Any], populate_query_metrics: bool | None = None, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, indexing_directive: Any | None = None, **kwargs: Any) -> Dict[str, Any]

Parâmetros

body

Obrigatório

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

pre_trigger_include

Obrigatório

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

post_trigger_include

Obrigatório

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

indexing_directive

Obrigatório

Indique se o documento deve ser omitido da indexação.

enable_automatic_id_generation: bool

Habilite a geração automática de ID 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

Um callable invocado com os metadados de resposta.

Retornos

Um ditado que representa o novo item.

Tipo de retorno

dict[str, Any]

Exceções

CosmosHttpResponseError

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.

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

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

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.

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

Parâmetros

conflict

Obrigatório

A ID (nome) ou o ditado que representa o conflito a ser excluído.

partition_key

Obrigatório

Chave de partição para o conflito a ser excluído.

response_hook: Callable

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.

delete_item(item: Dict[str, Any] | str, partition_key: Any, populate_query_metrics: bool | None = None, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, **kwargs: Any) -> None

Parâmetros

item

Obrigatório

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

partition_key

Obrigatório

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

pre_trigger_include

Obrigatório

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

post_trigger_include

Obrigatório

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

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.

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

Parâmetros

conflict

Obrigatório

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

partition_key

Obrigatório

Chave de partição para que o conflito seja recuperado.

response_hook: Callable

Um callable invocado com os metadados de resposta.

Retornos

Um ditado que representa o conflito recuperado.

Tipo de retorno

dict[str, Any]

Exceções

CosmosHttpResponseError

O conflito determinado não pôde ser recuperado.

get_throughput

Obtenha o objeto ThroughputProperties para este contêiner.

Se nenhuma ThroughputProperties já existir para o contêiner, uma exceção será gerada. :palavra-chave response_hook callable: um callable invocado com os metadados de resposta. :returns: taxa de transferência para o contêiner. :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

Item com a ID fornecida já existe.

list_conflicts

Liste todos os conflitos no contêiner.

list_conflicts(max_item_count: int | 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.

response_hook: Callable

Um callable invocado com os metadados de resposta.

Retornos

Um Iterável de conflitos (ditados).

Tipo de retorno

Iterable[dict[str, Any]]

Exceções

CosmosHttpResponseError

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.

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 ditado 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 às operações de patch.

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.

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

query_conflicts

Retornar todos os conflitos correspondentes a uma determinada consulta.

query_conflicts(query: str, parameters: List[str] | None = None, enable_cross_partition_query: bool | None = None, partition_key: Any | 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.

enable_cross_partition_query

Obrigatório

Permite o envio de mais de uma solicitação para executar a consulta no serviço do Azure Cosmos DB. Mais de uma solicitação será necessária se a consulta não estiver no escopo do valor de chave de partição única.

partition_key

Obrigatório

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

max_item_count

Obrigatório

Número máximo de itens 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 conflitos (ditados).

Tipo de retorno

Iterable[dict[str, Any]]

Exceções

CosmosHttpResponseError

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 é chamado de "p" para facilitar a referência na cláusula WHERE.

token de continuação de resposta na resposta da consulta. Os 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, as respostas têm a garantia de não serem mais obsoletas do que esse valor.

query_items(query: str, parameters: List[Dict[str, object]] | None = None, partition_key: Any | None = None, enable_cross_partition_query: bool | None = None, max_item_count: int | None = None, enable_scan_in_query: bool | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Retornos

Um iterável de itens (dicts).

Tipo de retorno

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

Exceções

CosmosHttpResponseError

Item com a ID fornecida já existe.

Exemplos

Obtenha todos os produtos que não foram descontinuados:


   import json

   for item in container.query_items(
       query='SELECT * FROM products p WHERE p.productModel <> "DISCONTINUED"',
       enable_cross_partition_query=True,
   ):
       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")],
   )
   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(partition_key_range_id: str | None = None, is_start_from_beginning: bool = False, continuation: str | None = None, max_item_count: int | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parâmetros

partition_key_range_id

Obrigatório

As solicitações 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.

partition_key

Obrigatório

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

is_start_from_beginning

Obrigatório

Obtenha se o feed de alterações deve começar do início (verdadeiro) ou do atual (falso). Por padrão, ele é iniciado do atual (falso).

continuation

Obrigatório

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

max_item_count

Obrigatório

Número máximo de itens 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 itens (dicts).

Tipo de retorno

Iterable[dict[str, Any]]

Exceções

CosmosHttpResponseError

Item com a ID fornecida já existe.

read

Leia as propriedades do contêiner.

read(*, populate_partition_key_range_statistics: bool | None = None, populate_quota_info: bool | None = None, **kwargs)

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

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

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, as respostas têm a garantia de não serem mais obsoletas do que esse valor.

Retornos

Um iterável de itens (dicts).

Tipo de retorno

Iterable[dict[str, Any]]

Exceções

CosmosHttpResponseError

Item com a ID fornecida já existe.

read_item

Obter o item identificado por item.

read_item(item: str | Dict[str, Any], partition_key: Any, populate_query_metrics: bool | None = None, post_trigger_include: str | None = None, **kwargs: Any) -> Dict[str, Any]

Parâmetros

item

Obrigatório

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

partition_key

Obrigatório

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

post_trigger_include

Obrigatório

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.

response_hook: Callable

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 = container.read_item("item2", partition_key="Widget")
   item["productModel"] = "DISCONTINUED"
   updated_item = container.upsert_item(item)

read_offer

Obtenha o objeto ThroughputProperties para esse contêiner. Se nenhuma ThroughputProperties já existir para o contêiner, uma exceção será gerada. :palavra-chave response_hook callable: um callable invocado com os metadados de resposta. :returns: taxa de transferência para o contêiner. :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) -> Offer

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

Item com a ID fornecida já existe.

replace_item

Substitui 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_item(item: str | Dict[str, Any], body: Dict[str, Any], populate_query_metrics: bool | None = None, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, **kwargs: Any) -> Dict[str, Any]

Parâmetros

item

Obrigatório

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

body

Obrigatório

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

pre_trigger_include

Obrigatório

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

post_trigger_include

Obrigatório

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

Um callable invocado com os metadados de resposta.

Retornos

Um dict 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.

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

upsert_item(body: Dict[str, Any], populate_query_metrics: bool | None = None, pre_trigger_include: str | None = None, post_trigger_include: str | None = None, **kwargs: Any) -> Dict[str, Any]

Parâmetros

body

Obrigatório

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

pre_trigger_include

Obrigatório

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

post_trigger_include

Obrigatório

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

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

O item especificado não pôde ser upserted.