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 get_container_client método para obter um contentor existente ou o 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, utilizando o SDK do Cosmos. A operação eliminar por chave de partição está restrita para 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, é 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. :keyword Callable response_hook: um callable invocado com os metadados de resposta. :returns: Débito para o contentor. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Não existem propriedades de débito para o contentor ou não foi possível obter as propriedades de débito.
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, é 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.
read_offer	Obtenha o objeto ThroughputProperties para este contentor. Se ainda não existirem ThroughputProperties para o contentor, é gerada uma exceção. :keyword Callable response_hook: um callable invocado com os metadados de resposta. :returns: Débito para o contentor. :gera ~azure.cosmos.exceptions.CosmosHttpResponseError: não existem propriedades de débito para o contentor ou não foi possível obter as propriedades de débito.
replace_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 .

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

Necessário

Um objeto semelhante a um ditado que representa o item a criar.

pre_trigger_include

Necessário

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

post_trigger_include

Necessário

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

indexing_directive

Necessário

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

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

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, utilizando o SDK do Cosmos. A operação eliminar por chave de partição está restrita para 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_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 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.

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

Parâmetros

conflict

Necessário

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

partition_key

Necessário

Chave de partição para o conflito eliminar.

response_hook: Callable

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, é gerada uma exceção.

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

Necessário

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

partition_key

Necessário

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

pre_trigger_include

Necessário

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

post_trigger_include

Necessário

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

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.

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

Parâmetros

conflict

Necessário

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

partition_key

Necessário

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

response_hook: Callable

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. :keyword Callable response_hook: um callable invocado com os metadados de resposta. :returns: Débito para o contentor. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Não existem propriedades de débito para o contentor ou

não foi possível obter as propriedades de débito.

get_throughput(**kwargs: Any) -> ThroughputProperties

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

O item com o ID especificado já existe.

list_conflicts

Liste todos os conflitos no contentor.

list_conflicts(max_item_count: int | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parâmetros

max_item_count

Necessário

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

response_hook: Callable

Um callable invocado com os metadados de resposta.

Devoluções

Iterável de conflitos (ditados).

Tipo de retorno

Iterable[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, é gerada uma exceção.

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

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

Necessário

A consulta SQL do Azure Cosmos DB a executar.

parameters

Necessário

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

enable_cross_partition_query

Necessário

Permite o envio de mais do que um pedido para executar a consulta no serviço Azure Cosmos DB. É necessário mais do que um pedido se a consulta não estiver no âmbito do valor da chave de partição única.

partition_key

Necessário

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

max_item_count

Necessário

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

response_hook: Callable

Um callable invocado com os metadados de resposta.

Devoluções

Iterável de conflitos (ditados).

Tipo de retorno

Iterable[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, 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]]

Devoluções

Iterável de itens (dicts).

Tipo de retorno

<xref:ItemPaged>[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

   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 ordenada de itens que foram alterados pela 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

Necessário

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.

partition_key

Necessário

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

is_start_from_beginning

Necessário

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

continuation

Necessário

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

max_item_count

Necessário

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

response_hook: Callable

Um callable invocado com os metadados de resposta.

Devoluções

Iterável de itens (dicts).

Tipo de retorno

Iterable[dict[str, Any]]

Exceções

CosmosHttpResponseError

O item com o ID especificado já existe.

read

Leia as propriedades do contentor.

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

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

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(max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parâmetros

max_item_count

Necessário

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

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

Iterável de itens (dicts).

Tipo de retorno

Iterable[dict[str, Any]]

Exceções

CosmosHttpResponseError

O item com o ID especificado já existe.

read_item

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

Necessário

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

partition_key

Necessário

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

post_trigger_include

Necessário

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

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

read_offer

Obtenha o objeto ThroughputProperties para este contentor. Se ainda não existirem ThroughputProperties para o contentor, é gerada uma exceção. :keyword Callable response_hook: um callable invocado com os metadados de resposta. :returns: Débito para o contentor. :gera ~azure.cosmos.exceptions.CosmosHttpResponseError: não existem propriedades de débito para o contentor ou

não foi possível obter as propriedades de débito.

read_offer(**kwargs: Any) -> Offer

Tipo de retorno

ThroughputProperties

Exceções

CosmosHttpResponseError

O item com o ID especificado já existe.

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

Necessário

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

body

Necessário

Um objeto tipo dict que representa o item a substituir.

pre_trigger_include

Necessário

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

post_trigger_include

Necessário

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

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.

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

Parâmetros

throughput

Necessário

O débito a definir (um número inteiro).

response_hook: Callable

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.

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

Necessário

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

pre_trigger_include

Necessário

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

post_trigger_include

Necessário

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

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.