DatabaseProxy Classe
Interfaccia per interagire con un database specifico.
Questa classe non deve essere creata direttamente. Usare invece il 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: data dell'ultimo aggiornamento della risorsa. Il valore è un timestamp.
_self: URI indirizzabile univoco per la risorsa.
_etag: l'etag delle risorse necessario per il controllo della concorrenza ottimistica.
_colls: percorso indirizzabile della risorsa delle raccolte.
_users: percorso indirizzabile della risorsa utenti.
- Ereditarietà
-
builtins.objectDatabaseProxy
Costruttore
DatabaseProxy(client_connection: CosmosClientConnection, id: str, properties: Dict[str, Any] = None)Parametri
- client_connection
- <xref:ClientSession>
Client da cui è stato recuperato questo database.
- properties
Variabili
- id
ID (nome) del database.
Metodi
| create_container |
Creare un nuovo contenitore con l'ID specificato (nome). 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 ciò che è stato passato 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 specificato (nome).
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) -> ContainerProxyParametri
- id
ID (nome) del contenitore da creare.
- partition_key
Chiave di partizione da usare per il contenitore.
- indexing_policy
Criteri di indicizzazione da applicare al contenitore.
- default_ttl
Tempo predefinito in tempo reale (TTL) per gli elementi nel contenitore. Se non specificato, gli elementi non scadono.
- offer_throughput
- int oppure <xref:azure.cosmos.ThroughputProperties.>
Velocità effettiva con provisioning per questa offerta.
- unique_key_policy
Criteri di chiave univoci da applicare al contenitore.
- conflict_resolution_policy
Criteri di risoluzione dei conflitti da applicare al contenitore.
- 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.
- analytical_storage_ttl
- int
Tempo di archiviazione analitica in tempo reale (TTL) per gli elementi nel contenitore. Un valore di Nessuno lascia l'archiviazione analitica disattivata e un valore di -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 di ContainerProxy che rappresenta il nuovo contenitore.
Tipo restituito
Eccezioni
La creazione del contenitore non è riuscita.
Esempio
Creare un contenitore con 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 ciò che è stato passato 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) -> ContainerProxyParametri
- id
ID (nome) del contenitore da leggere o creare.
- partition_key
Chiave di partizione da usare per il contenitore.
- indexing_policy
Criteri di indicizzazione da applicare al contenitore.
- default_ttl
Tempo predefinito in tempo reale (TTL) per gli elementi nel contenitore. Se non specificato, gli elementi non scadono.
- populate_query_metrics
Abilitare la restituzione delle metriche di query nelle intestazioni di risposta.
- offer_throughput
Velocità effettiva con provisioning per questa offerta.
- unique_key_policy
Criteri di chiave univoci da applicare al contenitore.
- conflict_resolution_policy
Criteri di risoluzione dei conflitti da applicare al contenitore.
- 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.
- analytical_storage_ttl
- int
Tempo di archiviazione analitica in tempo reale (TTL) per gli elementi nel contenitore. Un valore di Nessuno lascia l'archiviazione analitica disattivata e un valore di -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 di ContainerProxy che rappresenta il contenitore.
Tipo restituito
Eccezioni
Impossibile leggere o creare il contenitore.
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) -> UserProxyParametri
- body
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 costituito da non più di 255 caratteri.
- response_hook
- Callable
Chiamata richiamata con i metadati della risposta.
Restituisce
Istanza userProxy che rappresenta il nuovo utente.
Tipo restituito
Eccezioni
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) -> NoneParametri
- container
ID (nome) del contenitore da eliminare. È possibile passare l'ID del contenitore per eliminare, un'istanza o un ContainerProxy dict che rappresenta le proprietà del contenitore.
- 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
Eccezioni
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) -> NoneParametri
- user
ID (nome), dict che rappresenta le proprietà o UserProxy l'istanza dell'utente da eliminare.
- response_hook
- Callable
Chiamata richiamata con i metadati della risposta.
Tipo restituito
Eccezioni
L'utente non è stato eliminato correttamente.
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]) -> ContainerProxyParametri
- container
ID (nome) del contenitore, di un'istanza ContainerProxy o dict che rappresenta le proprietà del contenitore da recuperare.
Restituisce
Istanza containerProxy che rappresenta il database recuperato.
Tipo restituito
Eccezioni
La 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) -> ThroughputPropertiesTipo restituito
Eccezioni
La 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]) -> UserProxyParametri
- user
ID (nome), che rappresenta le proprietà o UserProxy l'istanza dell'utente da recuperare.
Restituisce
Istanza userProxy che rappresenta l'utente recuperato.
Tipo restituito
Eccezioni
La 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
Numero massimo di elementi da restituire nell'operazione di enumerazione.
- session_token
- str
Token da usare con coerenza della sessione.
- response_hook
- Callable
Oggetto chiamabile richiamato con i metadati della risposta.
Restituisce
Iterabile di proprietà del contenitore (dict).
Tipo restituito
Eccezioni
La 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
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
Eccezioni
La 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
Query SQL di Azure Cosmos DB da eseguire.
- parameters
Matrice facoltativa di parametri per la query. Ignorato se non viene specificata alcuna query.
- max_item_count
Numero massimo di elementi da restituire nell'operazione di enumerazione.
- session_token
- str
Token da usare con coerenza della sessione.
- response_hook
- Callable
Oggetto chiamabile richiamato con i metadati della risposta.
Restituisce
Iterabile di proprietà del contenitore (dict).
Tipo restituito
Eccezioni
La 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
Query SQL di Azure Cosmos DB da eseguire.
- parameters
Matrice facoltativa di parametri per la query. Ignorato se non viene specificata alcuna query.
- max_item_count
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
Eccezioni
La 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.
- response_hook
- Callable
Oggetto chiamabile richiamato con i metadati della risposta.
Tipo restituito
Eccezioni
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) -> ThroughputPropertiesTipo restituito
Eccezioni
La 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) -> ContainerProxyParametri
- container
ID (nome), che rappresenta le proprietà o ContainerProxy l'istanza del contenitore da sostituire.
- partition_key
Chiave di partizione da usare per il contenitore.
- indexing_policy
Criteri di indicizzazione da applicare al contenitore.
- default_ttl
Durata (TTL) predefinita per gli elementi nel contenitore. Se non specificato, gli elementi non scadono.
- conflict_resolution_policy
Criteri di risoluzione dei conflitti da applicare al contenitore.
- populate_query_metrics
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.
- 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
Eccezioni
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) -> ThroughputPropertiesParametri
- throughput
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
Eccezioni
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) -> UserProxyParametri
- user
ID (nome), che rappresenta le proprietà o UserProxy l'istanza dell'utente da sostituire.
- body
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
Eccezioni
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) -> UserProxyParametri
- body
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
Eccezioni
Se l'utente specificato non è riuscito a essere ignorato.
Azure SDK for Python