ContainerProxy Classe

Interfaccia per interagire con un contenitore di database specifico.

Questa classe non deve essere creata direttamente. Usare invece il <xref:azure.cosmos.aio.database.DatabaseProxy.get_container_client> metodo per ottenere un contenitore esistente o il <xref:azure.cosmos.aio.database.DatabaseProxy.create_container> metodo per creare un nuovo contenitore.

Un contenitore in un database DELL'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, utilizzare il upsert_item metodo .
delete_all_items_by_partition_key	La funzionalità di eliminazione 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% delle UR/sec totali 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	Ottiene il conflitto identificato dal conflitto.
get_throughput	Ottiene l'oggetto ThroughputProperties per questo contenitore. Se non esiste già un oggetto ThroughputProperties per il contenitore, viene generata un'eccezione.
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" ed è aliasato come "p" per facilitare l'esecuzione di riferimenti nella clausola WHERE. token di continuazione della risposta nella risposta alla query. I valori validi sono numeri interi positivi. Il valore 0 equivale a non passare un valore (impostazione predefinita nessun limite). :keyword int max_integrated_cache_staleness_in_ms: valore massimo di decadimento della cache per la cache integrata in Millisecondi. Per gli account configurati per l'uso della cache integrata, l'uso della coerenza di sessione o finale garantisce che le risposte non siano staler di questo valore.
query_items_change_feed	Ottiene 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	Ottiene l'elemento identificato dall'elemento.
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 esiste già un oggetto ThroughputProperties 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, utilizzare il upsert_item metodo .

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

Parametri

body

dict[str, str]

Necessario

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

pre_trigger_include

str

trigger ID da usare come trigger di pre-operazione.

post_trigger_include

str

trigger ID da usare come trigger post-operazione.

indexing_directive

Union[int, IndexingDirective]

Enumera i valori possibili per indicare se il documento deve essere omesso dall'indicizzazione. I valori possibili includono: 0 per Default, 1 per Exclude o 2 per Include.

enable_automatic_id_generation

bool

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

session_token

str

Token da usare con coerenza della 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 è stata modificata e agire in base alla condizione specificata dal parametro match_condition .

match_condition

MatchConditions

Condizione di corrispondenza da utilizzare sull'etag.

response_hook

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

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Oggetto 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à di eliminazione 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% delle UR/sec totali disponibili nel contenitore ogni secondo. Ciò consente di limitare le risorse usate da questa attività in background.

async 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

trigger ID da usare come trigger di pre-operazione.

post_trigger_include

str

trigger ID da usare come trigger post-operazione.

session_token

str

Token da usare con coerenza della sessione.

etag

str

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

match_condition

MatchConditions

Condizione di corrispondenza da utilizzare sull'etag.

response_hook

Callable

Oggetto chiamabile richiamato 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.

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

Parametri

conflict

Union[str, Dict[str, Any]]

Necessario

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

partition_key

Union[str, int, float, bool]

Necessario

Chiave di partizione per il conflitto da recuperare.

response_hook

Callable[[Dict[str, str], None], None]

Oggetto chiamabile richiamato 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.

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

Parametri

item

Union[str, Dict[str, Any]]

Necessario

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

partition_key

Union[str, int, float, bool]

Necessario

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

pre_trigger_include

str

trigger ID da usare come trigger di pre-operazione.

post_trigger_include

str

trigger ID da usare come trigger post-operazione.

session_token

str

Token da usare con coerenza della 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 è stata modificata e agire in base alla condizione specificata dal parametro match_condition .

match_condition

MatchConditions

Condizione di corrispondenza da utilizzare sull'etag.

response_hook

Callable[[Dict[str, str], None], None]

Oggetto chiamabile richiamato 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

Ottiene il conflitto identificato dal conflitto.

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

Parametri

conflict

Union[str, Dict[str, Any]]

Necessario

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

partition_key

Union[str, int, float, bool]

Necessario

Chiave di partizione per il conflitto da recuperare.

response_hook

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

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Dict che rappresenta il conflitto recuperato.

Tipo restituito

Dict[str, Any]

Eccezioni

CosmosHttpResponseError

Impossibile recuperare il conflitto specificato.

get_throughput

Ottiene l'oggetto ThroughputProperties per questo contenitore.

Se non esiste già un oggetto ThroughputProperties per il contenitore, viene generata un'eccezione.

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

Parametri

response_hook

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

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

ThroughputProperties per il contenitore.

Tipo restituito

ThroughputProperties

Eccezioni

CosmosHttpResponseError

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

list_conflicts

Elencare tutti i conflitti nel contenitore.

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

Parametri

max_item_count

int

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

response_hook

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

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Oggetto AsyncItemPaged di conflitti (dict).

Tipo restituito

<xref:AsyncItemPaged>[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.

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]

Parametri

item

Union[str, Dict[str, Any]]

Necessario

ID (nome) o dict che rappresenta l'elemento a cui applicare 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 di operazioni patch da applicare all'elemento.

filter_predicate

str

filtro condizionale da applicare alle operazioni patch.

pre_trigger_include

str

trigger ID da usare come trigger di pre-operazione.

post_trigger_include

str

trigger ID da usare come trigger post-operazione.

session_token

str

Token da usare con coerenza della sessione.

etag

str

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

match_condition

MatchConditions

Condizione di corrispondenza da utilizzare sull'etag.

response_hook

Callable

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Dict che rappresenta l'elemento dopo l'esecuzione delle operazioni di patch.

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 | Dict[str, Any], **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parametri

query

Union[str, Dict[str, Any]]

Necessario

Query SQL di Azure Cosmos DB da eseguire.

parameters

List[Dict[str, Any]]

Matrice facoltativa di parametri per la query. Ignorato se non viene specificata alcuna query.

partition_key

Union[str, int, float, bool]

Specifica il valore della chiave di partizione per l'elemento. Se non viene passato nessuno, verrà eseguita una query tra partizioni.

max_item_count

int

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

response_hook

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

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Oggetto AsyncItemPaged di conflitti (dict).

Tipo restituito

<xref:AsyncItemPaged>[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" ed è aliasato come "p" per facilitare l'esecuzione di riferimenti nella clausola WHERE.

token di continuazione della risposta nella risposta alla query. I valori validi sono numeri interi positivi. Il valore 0 equivale a non passare un valore (impostazione predefinita nessun limite). :keyword int max_integrated_cache_staleness_in_ms: valore massimo di decadimento della cache per la cache integrata in

Millisecondi. Per gli account configurati per l'uso della cache integrata, l'uso della coerenza di sessione o finale garantisce che le risposte non siano staler di questo valore.

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

Restituisce

Oggetto AsyncItemPaged di elementi (dict).

Tipo restituito

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

           async for item in container.query_items(
                   query='SELECT * FROM products p WHERE p.productModel <> "DISCONTINUED"'
           ):
               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")],
           )
           async for item in discontinued_items:
               print(json.dumps(item, indent=True))

query_items_change_feed

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

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

Parametri

is_start_from_beginning

bool

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

partition_key_range_id

str

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

continuation

str

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

max_item_count

int

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

partition_key

Union[str, int, float, bool]

chiave di partizione a cui vengono assegnate le richieste ChangeFeed.

response_hook

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

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Oggetto AsyncItemPaged di elementi (dict).

Tipo restituito

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

Eccezioni

CosmosHttpResponseError

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

read

Leggere le proprietà del contenitore.

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

Parametri

populate_partition_key_range_statistics

bool

Abilitare la restituzione delle statistiche dell'intervallo di chiavi di partizione 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 della sessione.

initial_headers

dict[str, str]

Intestazioni iniziali da inviare come parte della richiesta.

response_hook

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

Oggetto chiamabile richiamato 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(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parametri

max_item_count

int

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

session_token

str

Token da usare con coerenza della sessione.

initial_headers

dict[str, str]

Intestazioni iniziali da inviare come parte della richiesta.

response_hook

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

Oggetto chiamabile richiamato con i metadati della risposta.

max_integrated_cache_staleness_in_ms

int

Decadimento massimo della cache per la cache integrata in millisecondi. Per gli account configurati per l'uso della cache integrata, l'uso della coerenza di sessione o finale garantisce che le risposte non siano staler di questo valore.

Restituisce

Oggetto AsyncItemPaged di elementi (dict).

Tipo restituito

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

Eccezioni

CosmosHttpResponseError

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

read_item

Ottiene l'elemento identificato dall'elemento.

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

Parametri

item

Union[str, Dict[str, Any]]

Necessario

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

partition_key

Union[str, int, float, bool]

Necessario

Chiave di partizione per l'elemento da recuperare.

post_trigger_include

str

trigger ID da usare come trigger post-operazione.

session_token

str

Token da usare con coerenza della sessione.

initial_headers

dict[str, str]

Intestazioni iniziali da inviare come parte della richiesta.

response_hook

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

Oggetto chiamabile richiamato con i metadati della risposta.

max_integrated_cache_staleness_in_ms

int

Decadimento massimo della cache per la cache integrata in millisecondi. Per gli account configurati per l'uso della cache integrata, l'uso della coerenza di sessione o finale garantisce che le risposte non siano staler di questo valore.

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 aggiornarne una delle proprietà:

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

replace_item

Sostituisce l'elemento specificato, se presente nel contenitore.

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

async replace_item(item: str | Dict[str, Any], body: 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 sostituire.

body

Dict[str, Any]

Necessario

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

pre_trigger_include

str

trigger ID da usare come trigger di pre-operazione.

post_trigger_include

str

trigger ID da usare come trigger post-operazione.

session_token

str

Token da usare con coerenza della 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 è stata modificata e agire in base alla condizione specificata dal parametro match_condition .

match_condition

MatchConditions

Condizione di corrispondenza da utilizzare sull'etag.

response_hook

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

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Oggetto dict che rappresenta l'elemento dopo il passaggio della sostituzione.

Tipo restituito

Dict[str, Any]

Eccezioni

CosmosHttpResponseError

Sostituzione non riuscita o l'elemento con ID specificato non esiste.

replace_throughput

Sostituire la velocità effettiva del contenitore.

Se non esiste già un oggetto ThroughputProperties per il contenitore, viene generata un'eccezione.

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

Parametri

throughput

Union[int, ThroughputProperties]

Necessario

Velocità effettiva da impostare.

response_hook

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

Oggetto chiamabile richiamato 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.

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

Parametri

body

Dict[str, Any]

Necessario

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

pre_trigger_include

str

trigger ID da usare come trigger di pre-operazione.

post_trigger_include

str

trigger ID da usare come trigger post-operazione.

session_token

str

Token da usare con coerenza della 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 è stata modificata e agire in base alla condizione specificata dal parametro match_condition .

match_condition

MatchConditions

Condizione di corrispondenza da utilizzare sull'etag.

response_hook

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

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Oggetto dict che rappresenta l'elemento in alto.

Tipo restituito

Dict[str, Any]

Eccezioni

CosmosHttpResponseError

Impossibile eseguire l'upserted dell'elemento specificato.

Attributi

is_system_key

scripts