DatabaseProxy Classe

  • Riferimento

Interfaccia per interagire con un database specifico.

Questa classe non deve essere creata direttamente. Usare invece il <xref:CosmosClient.get_database_client> metodo .

Un database contiene uno o più contenitori, ognuno dei quali può contenere elementi, stored procedure, trigger e funzioni definite dall'utente.

Un database può anche avere utenti associati, ognuno dei quali è configurato con un set di autorizzazioni per l'accesso a determinati contenitori, stored procedure, trigger, funzioni definite dall'utente o elementi.

Un database DELL'API SQL di Azure Cosmos DB include le proprietà generate dal sistema seguenti. Queste proprietà sono di sola lettura:

  • _rid: ID risorsa.

  • _ts: quando la risorsa è stata aggiornata. Il valore è un timestamp.

  • _self: URI indirizzabile univoco per la risorsa.

  • _etag: l'etag delle risorse richiesto per il controllo di concorrenza ottimistica.

  • _colls: percorso indirizzabile della risorsa delle raccolte.

  • _users: percorso indirizzabile della risorsa utenti.

Ereditarietà
builtins.object
DatabaseProxy

Costruttore

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

Parametri

client_connection
<xref:ClientSession>
Necessario

Client da cui è stato recuperato il database.

id
str
Necessario

ID (nome) del database.

properties
valore predefinito: None

Variabili

id

ID (nome) del database.

Metodi

create_container

Creare un nuovo contenitore con l'ID (nome) specificato.

Se esiste già un contenitore con l'ID specificato, viene generato un oggetto CosmosResourceExistsError.
create_container_if_not_exists

Creare un contenitore se non esiste già.

Se il contenitore esiste già, vengono restituite le impostazioni esistenti. Nota: non controlla o aggiorna le impostazioni del contenitore esistenti o offre velocità effettiva se differiscono da quelle passate al metodo.
create_user

Creare un nuovo utente nel contenitore.

Per aggiornare o sostituire un utente esistente, usare il <xref:ContainerProxy.upsert_user> metodo .
delete_container

Elimina un contenitore.
delete_user

Eliminare l'utente specificato dal contenitore.
get_container_client

Ottenere un oggetto ContainerProxy per un contenitore con ID (nome) specificato.
get_throughput

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

Impossibile recuperare le proprietà della velocità effettiva.
get_user_client

Ottenere un userProxy per un utente con l'ID specificato.
list_containers

Elencare i contenitori nel database.
list_users

Elencare tutti gli utenti nel contenitore.
query_containers

Elencare le proprietà per i contenitori nel database corrente.
query_users

Restituisce tutti gli utenti corrispondenti alla query specificata.
read

Leggere le proprietà del database.
read_offer

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

Impossibile recuperare le proprietà della velocità effettiva.
replace_container

Reimpostare le proprietà del contenitore.

Le modifiche alle proprietà vengono rese persistenti immediatamente. Tutte le proprietà non specificate verranno reimpostate nei valori predefiniti.
replace_throughput

Sostituire la velocità effettiva a livello di database.
replace_user

Sostituisce l'utente specificato, se presente nel contenitore.
upsert_user

Inserire o aggiornare l'utente specificato.

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

create_container

Creare un nuovo contenitore con l'ID (nome) specificato.

Se esiste già un contenitore con l'ID specificato, viene generato un oggetto CosmosResourceExistsError.

create_container(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

Parametri

id
Necessario

ID (nome) del contenitore da creare.

partition_key
Necessario

Chiave di partizione da usare per il contenitore.

indexing_policy
Necessario

Criteri di indicizzazione da applicare al contenitore.

default_ttl
Necessario

Durata (TTL) predefinita per gli elementi nel contenitore. Se non specificato, gli elementi non scadono.

offer_throughput
int oppure <xref:azure.cosmos.ThroughputProperties.>
Necessario

Velocità effettiva con provisioning per questa offerta.

unique_key_policy
Necessario

Criteri di chiave univoca da applicare al contenitore.

conflict_resolution_policy
Necessario

Criteri di risoluzione dei conflitti da applicare al contenitore.

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

Oggetto chiamabile richiamato con i metadati della risposta.

analytical_storage_ttl
int

Durata (TTL) dell'archivio analitico per gli elementi nel contenitore. Il valore None lascia l'archiviazione analitica disattivata e il valore -1 attiva l'archiviazione analitica senza TTL. Si noti che l'archiviazione analitica può essere abilitata solo negli account abilitati Collegamento a Synapse.

Restituisce

Istanza containerProxy che rappresenta il nuovo contenitore.

Tipo restituito

ContainerProxy

Eccezioni

CosmosHttpResponseError

Creazione del contenitore non riuscita.

Esempio

Creare un contenitore con le impostazioni predefinite:


   container_name = "products"
   try:
       container = database.create_container(
           id=container_name, partition_key=PartitionKey(path="/productName")
       )
   except exceptions.CosmosResourceExistsError:
       container = database.get_container_client(container_name)

Creare un contenitore con impostazioni specifiche; in questo caso, una chiave di partizione personalizzata:


   customer_container_name = "customers"
   try:
       customer_container = database.create_container(
           id=customer_container_name,
           partition_key=PartitionKey(path="/city"),
           default_ttl=200,
       )
   except exceptions.CosmosResourceExistsError:
       customer_container = database.get_container_client(customer_container_name)

create_container_if_not_exists

Creare un contenitore se non esiste già.

Se il contenitore esiste già, vengono restituite le impostazioni esistenti. Nota: non controlla o aggiorna le impostazioni del contenitore esistenti o offre velocità effettiva se differiscono da quelle passate al metodo.

create_container_if_not_exists(id: str, partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, unique_key_policy: Dict[str, Any] | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, **kwargs: Any) -> ContainerProxy

Parametri

id
Necessario

ID (nome) del contenitore da leggere o creare.

partition_key
Necessario

Chiave di partizione da usare per il contenitore.

indexing_policy
Necessario

Criteri di indicizzazione da applicare al contenitore.

default_ttl
Necessario

Durata (TTL) predefinita per gli elementi nel contenitore. Se non specificato, gli elementi non scadono.

populate_query_metrics
Necessario

Abilitare la restituzione delle metriche di query nelle intestazioni di risposta.

offer_throughput
Necessario

Velocità effettiva con provisioning per questa offerta.

unique_key_policy
Necessario

Criteri di chiave univoca da applicare al contenitore.

conflict_resolution_policy
Necessario

Criteri di risoluzione dei conflitti da applicare al contenitore.

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

Oggetto chiamabile richiamato con i metadati della risposta.

analytical_storage_ttl
int

Durata (TTL) dell'archivio analitico per gli elementi nel contenitore. Il valore None lascia l'archiviazione analitica disattivata e il valore -1 attiva l'archiviazione analitica senza TTL. Si noti che l'archiviazione analitica può essere abilitata solo negli account abilitati Collegamento a Synapse.

Restituisce

Istanza containerProxy che rappresenta il contenitore.

Tipo restituito

ContainerProxy

Eccezioni

CosmosHttpResponseError

Lettura o creazione del contenitore non riuscita.

create_user

Creare un nuovo utente nel contenitore.

Per aggiornare o sostituire un utente esistente, usare il <xref:ContainerProxy.upsert_user> metodo .

create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

Parametri

body
Necessario

Oggetto dict-like con una chiave ID e un valore che rappresenta l'utente da creare. L'ID utente deve essere univoco all'interno del database e deve contenere non più di 255 caratteri.

response_hook
Callable

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Istanza userProxy che rappresenta il nuovo utente.

Tipo restituito

UserProxy

Eccezioni

CosmosHttpResponseError

Se non è stato possibile creare l'utente specificato.

Esempio

Creare un utente del database:


   try:
       database.create_user(dict(id="Walter Harp"))
   except exceptions.CosmosResourceExistsError:
       print("A user with that ID already exists.")
   except exceptions.CosmosHttpResponseError as failure:
       print("Failed to create user. Status code:{}".format(failure.status_code))

delete_container

Elimina un contenitore.

delete_container(container: str | ContainerProxy | Dict[str, Any], populate_query_metrics: bool | None = None, **kwargs: Any) -> None

Parametri

container
Necessario

ID (nome) del contenitore da eliminare. È possibile passare l'ID del contenitore da eliminare, un'istanza <xref:azure.cosmos.database.ContainerProxy> o un dict che rappresenta le proprietà del contenitore.

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

Oggetto chiamabile richiamato con i metadati della risposta.

Tipo restituito

None

Eccezioni

CosmosHttpResponseError

Se non è stato possibile eliminare il contenitore.

delete_user

Eliminare l'utente specificato dal contenitore.

delete_user(user: str | UserProxy | Dict[str, Any], **kwargs: Any) -> None

Parametri

user
Necessario

ID (nome), che rappresenta le proprietà o <xref:azure.cosmos.database.UserProxy> l'istanza dell'utente da eliminare.

response_hook
Callable

Oggetto chiamabile richiamato con i metadati della risposta.

Tipo restituito

None

Eccezioni

CosmosHttpResponseError

L'utente non è stato eliminato correttamente.

CosmosResourceNotFoundError

L'utente non esiste nel contenitore.

get_container_client

Ottenere un oggetto ContainerProxy per un contenitore con ID (nome) specificato.

get_container_client(container: str | ContainerProxy | Dict[str, Any]) -> ContainerProxy

Parametri

container
Necessario

ID (nome) del contenitore, di un'istanza <xref:azure.cosmos.database.ContainerProxy> o dict che rappresenta le proprietà del contenitore da recuperare.

Restituisce

Istanza containerProxy che rappresenta il database recuperato.

Tipo restituito

ContainerProxy

Eccezioni

CosmosHttpResponseError

Creazione del contenitore non riuscita.

Esempio

Ottenere un contenitore esistente, gestendo un errore se rilevato:


   database = client.get_database_client(database_name)
   container = database.get_container_client(container_name)

get_throughput

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

Impossibile recuperare le proprietà della velocità effettiva.

get_throughput(**kwargs: Any) -> ThroughputProperties

Tipo restituito

ThroughputProperties

Eccezioni

CosmosHttpResponseError

Creazione del contenitore non riuscita.

get_user_client

Ottenere un userProxy per un utente con l'ID specificato.

get_user_client(user: str | UserProxy | Dict[str, Any]) -> UserProxy

Parametri

user
Necessario

ID (nome), che rappresenta le proprietà o <xref:azure.cosmos.database.UserProxy> l'istanza dell'utente da recuperare.

Restituisce

Istanza userProxy che rappresenta l'utente recuperato.

Tipo restituito

UserProxy

Eccezioni

CosmosHttpResponseError

Creazione del contenitore non riuscita.

list_containers

Elencare i contenitori nel database.

list_containers(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 della sessione.

initial_headers
dict[str,str]

Intestazioni iniziali da inviare come parte della richiesta.

response_hook
Callable

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Iterabile di proprietà del contenitore (dict).

Tipo restituito

Iterable[dict[str, Any]]

Eccezioni

CosmosHttpResponseError

Creazione del contenitore non riuscita.

Esempio

Elencare tutti i contenitori nel database:


   database = client.get_database_client(database_name)
   for container in database.list_containers():
       print("Container ID: {}".format(container['id']))

list_users

Elencare tutti gli utenti nel contenitore.

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

Parametri

max_item_count
Necessario

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

response_hook
Callable

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Iterabile di proprietà utente (dict).

Tipo restituito

Iterable[dict[str, Any]]

Eccezioni

CosmosHttpResponseError

Creazione del contenitore non riuscita.

query_containers

Elencare le proprietà per i contenitori nel database corrente.

query_containers(query: str | None = None, parameters: List[str] | None = None, max_item_count: int | None = None, populate_query_metrics: bool | 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 per la query. Ignorato se non viene specificata alcuna query.

max_item_count
Necessario

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

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Iterabile di proprietà del contenitore (dict).

Tipo restituito

Iterable[dict[str, Any]]

Eccezioni

CosmosHttpResponseError

Creazione del contenitore non riuscita.

query_users

Restituisce tutti gli utenti corrispondenti alla query specificata.

query_users(query: str, parameters: List[str] | 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 per la query. Ignorato se non viene specificata alcuna query.

max_item_count
Necessario

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

response_hook
Callable

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Iterabile di proprietà utente (dict).

Tipo restituito

Iterable[str, Any]

Eccezioni

CosmosHttpResponseError

Creazione del contenitore non riuscita.

read

Leggere le proprietà del database.

read(populate_query_metrics: bool | None = None, **kwargs: Any) -> Dict[str, Any]

Parametri

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

Oggetto chiamabile richiamato con i metadati della risposta.

Tipo restituito

Dict[<xref:Str>, Any]

Eccezioni

CosmosHttpResponseError

Se non è stato possibile recuperare il database specificato.

read_offer

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

Impossibile recuperare le proprietà della velocità effettiva.

read_offer(**kwargs: Any) -> ThroughputProperties

Tipo restituito

ThroughputProperties

Eccezioni

CosmosHttpResponseError

Creazione del contenitore non riuscita.

replace_container

Reimpostare le proprietà del contenitore.

Le modifiche alle proprietà vengono rese persistenti immediatamente. Tutte le proprietà non specificate verranno reimpostate nei valori predefiniti.

replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: Any, indexing_policy: Dict[str, Any] | None = None, default_ttl: int | None = None, conflict_resolution_policy: Dict[str, Any] | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> ContainerProxy

Parametri

container
Necessario

ID (nome), che rappresenta le proprietà o <xref:azure.cosmos.database.ContainerProxy> l'istanza del contenitore da sostituire.

partition_key
Necessario

Chiave di partizione da usare per il contenitore.

indexing_policy
Necessario

Criteri di indicizzazione da applicare al contenitore.

default_ttl
Necessario

Durata (TTL) predefinita per gli elementi nel contenitore. Se non specificato, gli elementi non scadono.

conflict_resolution_policy
Necessario

Criteri di risoluzione dei conflitti da applicare al contenitore.

populate_query_metrics
Necessario

Abilitare la restituzione delle metriche di query nelle intestazioni di risposta.

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.

initial_headers
dict[str,str]

Intestazioni iniziali da inviare come parte della richiesta.

response_hook
Callable

Oggetto chiamabile richiamato con i metadati della risposta.

analytical_storage_ttl
int

Durata (TTL) dell'archivio analitico per gli elementi nel contenitore. Il valore None lascia l'archiviazione analitica disattivata e il valore -1 attiva l'archiviazione analitica senza TTL. Si noti che l'archiviazione analitica può essere abilitata solo negli account abilitati Collegamento a Synapse.

Restituisce

Istanza containerProxy che rappresenta il contenitore dopo il completamento della sostituzione.

Tipo restituito

ContainerProxy

Eccezioni

CosmosHttpResponseError

Generato se non è stato possibile sostituire il contenitore. Ciò include se il contenitore con ID specificato non esiste.

Esempio

Reimpostare la proprietà TTL in un contenitore e visualizzare le proprietà aggiornate:


   # Set the TTL on the container to 3600 seconds (one hour)
   database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)

   # Display the new TTL setting for the container
   container_props = database.get_container_client(container_name).read()
   print("New container TTL: {}".format(json.dumps(container_props['defaultTtl'])))

replace_throughput

Sostituire la velocità effettiva a livello di database.

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

Parametri

throughput
Necessario

Velocità effettiva da impostare (un numero intero).

response_hook
Callable

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

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

Tipo restituito

ThroughputProperties

Eccezioni

CosmosHttpResponseError

Se non esistono proprietà di velocità effettiva per il database o se non è stato possibile aggiornare le proprietà della velocità effettiva.

replace_user

Sostituisce l'utente specificato, se presente nel contenitore.

replace_user(user: str | UserProxy | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxy

Parametri

user
Necessario

ID (nome), che rappresenta le proprietà o <xref:azure.cosmos.database.UserProxy> l'istanza dell'utente da sostituire.

body
Necessario

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

response_hook
Callable

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Istanza userProxy che rappresenta l'utente dopo che è stata sostituita.

Tipo restituito

UserProxy

Eccezioni

CosmosHttpResponseError

Se la sostituzione non è riuscita o l'utente con id specificato non esiste.

upsert_user

Inserire o aggiornare l'utente specificato.

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

upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxy

Parametri

body
Necessario

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

response_hook
Callable

Oggetto chiamabile richiamato con i metadati della risposta.

Restituisce

Istanza di UserProxy che rappresenta l'utente con stato in alto.

Tipo restituito

UserProxy

Eccezioni

CosmosHttpResponseError

Se l'utente specificato non è riuscito a essere ignorato.