ContainerProxy Classe

Riferimento

Interfaccia da interagire con un contenitore di database specifico.

Questa classe non deve essere creata direttamente. Usare invece il get_container_client metodo per ottenere un contenitore esistente o il create_container metodo per creare un nuovo contenitore.

Un contenitore in un database API SQL di Azure Cosmos DB è una raccolta di documenti, ognuno dei quali è rappresentato come elemento.

Ereditarietà: builtins.object

ContainerProxy

Costruttore

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

Parametri

client_connection

database_link

id

properties

valore predefinito: None

Variabili

id: str

ID (nome) del contenitore

session_token: str

Token di sessione per il contenitore.

Metodi

create_item	Creare un elemento nel contenitore. Per aggiornare o sostituire un elemento esistente, usare il upsert_item metodo .
delete_all_items_by_partition_key	La funzionalità elimina per chiave di partizione è un'operazione in background asincrona che consente di eliminare tutti i documenti con lo stesso valore della chiave di partizione logica, usando Cosmos SDK. L'operazione di eliminazione per chiave di partizione è vincolata a utilizzare al massimo il 10% del totale delle UR/s disponibili nel contenitore ogni secondo. Ciò consente di limitare le risorse usate da questa attività in background.
delete_conflict	Eliminare un conflitto specificato dal contenitore. Se il conflitto non esiste già nel contenitore, viene generata un'eccezione.
delete_item	Eliminare l'elemento specificato dal contenitore. Se l'elemento non esiste già nel contenitore, viene generata un'eccezione.
get_conflict	Ottenere il conflitto identificato dal conflitto.
get_throughput	Ottenere l'oggetto ThroughputProperties per questo contenitore. Se non esistono già proprietà di velocità effettiva per il contenitore, viene generata un'eccezione. :keyword Callable response_hook: una chiamata richiamata con i metadati della risposta. :restituisce: velocità effettiva per il contenitore. :genera ~azure.cosmos.exceptions.CosmosHttpResponseError: nessuna proprietà di velocità effettiva esiste per il contenitore o Impossibile recuperare le proprietà della velocità effettiva.
list_conflicts	Elencare tutti i conflitti nel contenitore.
patch_item	Metodo provvisorio Applica patch all'elemento specificato con le operazioni fornite se presente nel contenitore. Se l'elemento non esiste già nel contenitore, viene generata un'eccezione.
query_conflicts	Restituisce tutti i conflitti corrispondenti a una determinata query.
query_items	Restituisce tutti i risultati corrispondenti alla query specificata. È possibile usare qualsiasi valore per il nome del contenitore nella clausola FROM, ma spesso viene usato il nome del contenitore. Negli esempi seguenti il nome del contenitore è "products" e viene aliasato come "p" per un riferimento più semplice nella clausola WHERE. token di continuazione della risposta alla risposta alla query. I valori validi sono interi positivi. Un valore pari a 0 è uguale a quello di non passare un valore (valore predefinito senza limite). :keyword int max_integrated_cache_staleness_in_ms: il numero massimo di cache non aggiornato per la cache integrata in Millisecondi. Per gli account configurati per l'uso della cache integrata, usando la coerenza sessione o finale, le risposte non devono essere più aggiornate di questo valore.
query_items_change_feed	Ottenere un elenco ordinato di elementi modificati, nell'ordine in cui sono stati modificati.
read	Leggere le proprietà del contenitore.
read_all_items	Elencare tutti gli elementi nel contenitore.
read_item	Ottenere l'elemento identificato dall'elemento.
read_offer	Ottenere l'oggetto ThroughputProperties per questo contenitore. Se non esistono già proprietà di velocità effettiva per il contenitore, viene generata un'eccezione. :keyword Callable response_hook: una chiamata richiamata con i metadati della risposta. :restituisce: velocità effettiva per il contenitore. :genera ~azure.cosmos.exceptions.CosmosHttpResponseError: nessuna proprietà di velocità effettiva esiste per il contenitore o Impossibile recuperare le proprietà della velocità effettiva.
replace_item	Sostituisce l'elemento specificato se presente nel contenitore. Se l'elemento non esiste già nel contenitore, viene generata un'eccezione.
replace_throughput	Sostituire la velocità effettiva del contenitore. Se non esistono già proprietà di velocità effettiva per il contenitore, viene generata un'eccezione.
upsert_item	Inserire o aggiornare l'elemento specificato. Se l'elemento esiste già nel contenitore, viene sostituito. Se l'elemento non esiste già, viene inserito.

create_item

Creare un elemento nel contenitore.

Per aggiornare o sostituire un elemento esistente, usare il upsert_item metodo .

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]

Parametri

body

Necessario

Oggetto dict-like che rappresenta l'elemento da creare.

pre_trigger_include

Necessario

id trigger da usare come trigger di pre-operazione.

post_trigger_include

Necessario

id trigger da usare come trigger post-operazione.

indexing_directive

Necessario

Indica se il documento deve essere omesso dall'indicizzazione.

enable_automatic_id_generation: bool

Abilitare la generazione automatica dell'ID se non è presente alcun ID.

session_token: str

Token da usare con coerenza sessione.

initial_headers: dict[str,str]

Intestazioni iniziali da inviare come parte della richiesta.

etag: str

Valore ETag o il carattere jolly (*). Usato per verificare se la risorsa è cambiata e agire in base alla condizione specificata dal parametro match_condition .

match_condition: MatchConditions

Condizione di corrispondenza da utilizzare sul etag.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

Restituisce

Dict che rappresenta il nuovo elemento.

Tipo restituito

dict[str, Any]

Eccezioni

CosmosHttpResponseError

L'elemento con l'ID specificato esiste già.

delete_all_items_by_partition_key

La funzionalità elimina per chiave di partizione è un'operazione in background asincrona che consente di eliminare tutti i documenti con lo stesso valore della chiave di partizione logica, usando Cosmos SDK. L'operazione di eliminazione per chiave di partizione è vincolata a utilizzare al massimo il 10% del totale delle UR/s disponibili nel contenitore ogni secondo. Ciò consente di limitare le risorse usate da questa attività in background.

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

Parametri

partition_key: Any

Necessario

Chiave di partizione per gli elementi da eliminare.

pre_trigger_include: str

id trigger da usare come trigger di pre-operazione.

post_trigger_include: str

id trigger da usare come trigger post-operazione.

session_token: str

Token da usare con coerenza sessione.

etag: str

Valore ETag o il carattere jolly (*). Usato per verificare se la risorsa è cambiata e agire in base alla condizione specificata dal parametro match_condition .

match_condition: MatchConditions

Condizione di corrispondenza da utilizzare sul etag.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

Tipo restituito

None

Eccezioni

CosmosHttpResponseError

L'elemento con l'ID specificato esiste già.

delete_conflict

Eliminare un conflitto specificato dal contenitore.

Se il conflitto non esiste già nel contenitore, viene generata un'eccezione.

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

Parametri

conflict

Necessario

ID (nome) o dict che rappresenta il conflitto da eliminare.

partition_key

Necessario

Chiave di partizione per l'eliminazione del conflitto.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

Tipo restituito

None

Eccezioni

CosmosHttpResponseError

Il conflitto non è stato eliminato correttamente.

CosmosResourceNotFoundError

Il conflitto non esiste nel contenitore.

delete_item

Eliminare l'elemento specificato dal contenitore.

Se l'elemento non esiste già nel contenitore, viene generata un'eccezione.

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

Parametri

item

Necessario

ID (nome) o dict che rappresenta l'elemento da eliminare.

partition_key

Necessario

Specifica il valore della chiave di partizione per l'elemento.

pre_trigger_include

Necessario

id trigger da usare come trigger di pre-operazione.

post_trigger_include

Necessario

id trigger da usare come trigger post-operazione.

session_token: str

Token da usare con coerenza sessione.

initial_headers: dict[str,str]

Intestazioni iniziali da inviare come parte della richiesta.

etag: str

Valore ETag o il carattere jolly (*). Usato per verificare se la risorsa è cambiata e agire in base alla condizione specificata dal parametro match_condition .

match_condition: MatchConditions

Condizione di corrispondenza da utilizzare sul etag.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

Tipo restituito

None

Eccezioni

CosmosHttpResponseError

L'elemento non è stato eliminato correttamente.

CosmosResourceNotFoundError

L'elemento non esiste nel contenitore.

get_conflict

Ottenere il conflitto identificato dal conflitto.

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

Parametri

conflict

Necessario

ID (nome) o dict che rappresenta il conflitto da recuperare.

partition_key

Necessario

Chiave di partizione per il recupero del conflitto.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

Restituisce

Un dict che rappresenta il conflitto recuperato.

Tipo restituito

dict[str, Any]

Eccezioni

CosmosHttpResponseError

Impossibile recuperare il conflitto specificato.

get_throughput

Ottenere l'oggetto ThroughputProperties per questo contenitore.

Se non esistono già proprietà di velocità effettiva per il contenitore, viene generata un'eccezione. :keyword Callable response_hook: una chiamata richiamata con i metadati della risposta. :restituisce: velocità effettiva per il contenitore. :genera ~azure.cosmos.exceptions.CosmosHttpResponseError: nessuna proprietà di velocità effettiva esiste per il contenitore o

Impossibile recuperare le proprietà della velocità effettiva.

get_throughput(**kwargs: Any) -> ThroughputProperties

Tipo restituito

ThroughputProperties

Eccezioni

CosmosHttpResponseError

L'elemento con l'ID specificato esiste già.

list_conflicts

Elencare tutti i conflitti nel contenitore.

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

Parametri

max_item_count

Necessario

Numero massimo di elementi da restituire nell'operazione di enumerazione.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

Restituisce

Iterabile dei conflitti (dict).

Tipo restituito

Iterable[dict[str, Any]]

Eccezioni

CosmosHttpResponseError

L'elemento con l'ID specificato esiste già.

patch_item

Metodo provvisorio Applica patch all'elemento specificato con le operazioni fornite se presente nel contenitore.

Se l'elemento non esiste già nel contenitore, viene generata un'eccezione.

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

Parametri

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

Necessario

ID (nome) o dict che rappresenta l'elemento da applicare a patch.

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

Necessario

Chiave di partizione dell'oggetto da applicare a patch.

patch_operations: List[Dict[str, Any]]

Necessario

Elenco delle operazioni di patch da applicare all'elemento.

filter_predicate: str

filtro condizionale da applicare alle operazioni patch.

pre_trigger_include: str

id trigger da usare come trigger di pre-operazione.

post_trigger_include: str

id trigger da usare come trigger post-operazione.

session_token: str

Token da usare con coerenza sessione.

etag: str

Valore ETag o il carattere jolly (*). Usato per verificare se la risorsa è cambiata e agire in base alla condizione specificata dal parametro match_condition .

match_condition: MatchConditions

Condizione di corrispondenza da utilizzare sul etag.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

Restituisce

Un dict che rappresenta l'elemento dopo che le operazioni di patch sono passate.

Tipo restituito

dict[str, Any]

Eccezioni

CosmosHttpResponseError

Le operazioni di patch non sono riuscite o l'elemento con ID specificato non esiste.

query_conflicts

Restituisce tutti i conflitti corrispondenti a una determinata query.

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

Parametri

query

Necessario

Query SQL di Azure Cosmos DB da eseguire.

parameters

Necessario

Matrice facoltativa di parametri nella query. Ignorato se non viene fornita alcuna query.

enable_cross_partition_query

Necessario

Consente l'invio di più richieste per eseguire la query nel servizio Azure Cosmos DB. È necessaria più di una richiesta se la query non è con ambito per il valore della chiave di partizione singola.

partition_key

Necessario

Specifica il valore della chiave di partizione per l'elemento.

max_item_count

Necessario

Numero massimo di elementi da restituire nell'operazione di enumerazione.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

Restituisce

Iterabile dei conflitti (dict).

Tipo restituito

Iterable[dict[str, Any]]

Eccezioni

CosmosHttpResponseError

L'elemento con l'ID specificato esiste già.

query_items

Restituisce tutti i risultati corrispondenti alla query specificata.

È possibile usare qualsiasi valore per il nome del contenitore nella clausola FROM, ma spesso viene usato il nome del contenitore. Negli esempi seguenti il nome del contenitore è "products" e viene aliasato come "p" per un riferimento più semplice nella clausola WHERE.

token di continuazione della risposta alla risposta alla query. I valori validi sono interi positivi. Un valore pari a 0 è uguale a quello di non passare un valore (valore predefinito senza limite). :keyword int max_integrated_cache_staleness_in_ms: il numero massimo di cache non aggiornato per la cache integrata in

Millisecondi. Per gli account configurati per l'uso della cache integrata, usando la coerenza sessione o finale, le risposte non devono essere più aggiornate di questo valore.

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

Restituisce

Iterabile di elementi (dict).

Tipo restituito

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

Eccezioni

CosmosHttpResponseError

L'elemento con l'ID specificato esiste già.

Esempio

Ottenere tutti i prodotti che non sono stati interrotti:


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

Query con parametri per ottenere tutti i prodotti che sono stati interrotti:


   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

Ottenere un elenco ordinato di elementi modificati, nell'ordine in cui sono stati modificati.

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

Parametri

partition_key_range_id

Necessario

Le richieste ChangeFeed possono essere eseguite in intervalli di chiavi di partizione specifici. Viene usato per elaborare il feed di modifiche in parallelo tra più consumer.

partition_key

Necessario

chiave di partizione in cui vengono destinate le richieste ChangeFeed.

is_start_from_beginning

Necessario

Ottenere se il feed di modifiche deve iniziare dall'inizio (true) o dall'oggetto corrente (false). Per impostazione predefinita, inizia da corrente (false).

continuation

Necessario

e_tag valore da usare come continuazione per la lettura del feed di modifiche.

max_item_count

Necessario

Numero massimo di elementi da restituire nell'operazione di enumerazione.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

Restituisce

Iterabile di elementi (dict).

Tipo restituito

Iterable[dict[str, Any]]

Eccezioni

CosmosHttpResponseError

L'elemento con l'ID specificato esiste già.

read

Leggere le proprietà del contenitore.

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

Parametri

populate_partition_key_range_statistics: bool

Abilitare le statistiche dell'intervallo di chiavi di partizione restituite nelle intestazioni di risposta.

populate_quota_info: bool

Abilitare la restituzione delle informazioni sulla quota di archiviazione della raccolta nelle intestazioni di risposta.

session_token: str

Token da usare con coerenza sessione.

initial_headers: dict[str,str]

Intestazioni iniziali da inviare come parte della richiesta.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

Restituisce

Dict che rappresenta il contenitore recuperato.

Tipo restituito

dict[str, Any]

Eccezioni

CosmosHttpResponseError

Generato se non è stato possibile recuperare il contenitore. Ciò include se il contenitore non esiste.

read_all_items

Elencare tutti gli elementi nel contenitore.

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

Parametri

max_item_count

Necessario

Numero massimo di elementi da restituire nell'operazione di enumerazione.

session_token: str

Token da usare con coerenza sessione.

initial_headers: dict[str,str]

Intestazioni iniziali da inviare come parte della richiesta.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

max_integrated_cache_staleness_in_ms: int

Il valore massimo della cache non aggiornato per la cache integrata in millisecondi. Per gli account configurati per l'uso della cache integrata, usando la coerenza sessione o finale, le risposte non devono essere più aggiornate di questo valore.

Restituisce

Iterabile di elementi (dict).

Tipo restituito

Iterable[dict[str, Any]]

Eccezioni

CosmosHttpResponseError

L'elemento con l'ID specificato esiste già.

read_item

Ottenere l'elemento identificato dall'elemento.

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]

Parametri

item

Necessario

ID (nome) o dict che rappresenta l'elemento da recuperare.

partition_key

Necessario

Chiave di partizione per l'elemento da recuperare.

post_trigger_include

Necessario

id trigger da usare come trigger post-operazione.

session_token: str

Token da usare con coerenza sessione.

initial_headers: dict[str,str]

Intestazioni iniziali da inviare come parte della richiesta.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

max_integrated_cache_staleness_in_ms: int

Restituisce

Dict che rappresenta l'elemento da recuperare.

Tipo restituito

dict[str, Any]

Eccezioni

CosmosHttpResponseError

Impossibile recuperare l'elemento specificato.

Esempio

Ottenere un elemento dal database e aggiornare una delle relative proprietà:


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

read_offer

Ottenere l'oggetto ThroughputProperties per questo contenitore. Se non esistono già proprietà di velocità effettiva per il contenitore, viene generata un'eccezione. :keyword Callable response_hook: una chiamata richiamata con i metadati della risposta. :restituisce: velocità effettiva per il contenitore. :genera ~azure.cosmos.exceptions.CosmosHttpResponseError: nessuna proprietà di velocità effettiva esiste per il contenitore o

Impossibile recuperare le proprietà della velocità effettiva.

read_offer(**kwargs: Any) -> Offer

Tipo restituito

ThroughputProperties

Eccezioni

CosmosHttpResponseError

L'elemento con l'ID specificato esiste già.

replace_item

Sostituisce l'elemento specificato se presente nel contenitore.

Se l'elemento non esiste già nel contenitore, viene generata un'eccezione.

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]

Parametri

item

Necessario

ID (nome) o dict che rappresenta l'elemento da sostituire.

body

Necessario

Oggetto simile a ct che rappresenta l'elemento da sostituire.

pre_trigger_include

Necessario

id trigger da usare come trigger di pre-operazione.

post_trigger_include

Necessario

id trigger da usare come trigger post-operazione.

session_token: str

Token da usare con coerenza sessione.

initial_headers: dict[str,str]

Intestazioni iniziali da inviare come parte della richiesta.

etag: str

Valore ETag o il carattere jolly (*). Usato per verificare se la risorsa è cambiata e agire in base alla condizione specificata dal parametro match_condition .

match_condition: MatchConditions

Condizione di corrispondenza da utilizzare sul etag.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

Restituisce

Un dict che rappresenta l'elemento dopo aver eseguito la sostituzione.

Tipo restituito

dict[str, Any]

Eccezioni

CosmosHttpResponseError

La sostituzione non è riuscita o l'elemento con ID specificato non esiste.

replace_throughput

Sostituire la velocità effettiva del contenitore.

Se non esistono già proprietà di velocità effettiva per il contenitore, viene generata un'eccezione.

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

Parametri

throughput

Necessario

Velocità effettiva da impostare (intero).

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

Restituisce

ThroughputProperties per il contenitore, aggiornato con una nuova velocità effettiva.

Tipo restituito

ThroughputProperties

Eccezioni

CosmosHttpResponseError

Non è possibile aggiornare le proprietà della velocità effettiva per il contenitore o le proprietà di velocità effettiva.

upsert_item

Inserire o aggiornare l'elemento specificato.

Se l'elemento esiste già nel contenitore, viene sostituito. Se l'elemento non esiste già, viene inserito.

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]

Parametri

body

Necessario

Oggetto simile a ct che rappresenta l'elemento da aggiornare o inserire.

pre_trigger_include

Necessario

id trigger da usare come trigger di pre-operazione.

post_trigger_include

Necessario

id trigger da usare come trigger post-operazione.

session_token: str

Token da usare con coerenza sessione.

initial_headers: dict[str,str]

Intestazioni iniziali da inviare come parte della richiesta.

etag: str

Valore ETag o il carattere jolly (*). Usato per verificare se la risorsa è cambiata e agire in base alla condizione specificata dal parametro match_condition .

match_condition: MatchConditions

Condizione di corrispondenza da utilizzare sul etag.

response_hook: Callable

Chiamata richiamata con i metadati della risposta.

Restituisce

Oggetto dict che rappresenta l'elemento upserted.

Tipo restituito

dict[str, Any]

Eccezioni

CosmosHttpResponseError

Impossibile eseguire l'upserted dell'elemento specificato.