DatabaseProxy Classe
Interfaccia per interagire con un database specifico.
Questa classe non deve essere creata direttamente. Usare invece il <xref:azure.cosmos.aio.cosmos_client.CosmosClient.get_database_client> metodo per ottenere un database esistente o il <xref:azure.cosmos.aio.cosmos_client.CosmosClient.create_database> metodo per creare un nuovo database.
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:azure.cosmos.aio.CosmosClientConnection>
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. |
| 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. |
| 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. Se non esiste già un oggetto ThroughputProperties per il database, viene generata un'eccezione. |
| 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.
async create_container(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyParametri
- default_ttl
- int
Tempo predefinito in tempo reale (TTL) per gli elementi nel contenitore. Se non specificato, gli elementi non scadono.
- offer_throughput
- Union[int, ThroughputProperties]
Velocità effettiva con provisioning per questa offerta.
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.
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 = await 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 = await 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.
async create_container_if_not_exists(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyParametri
- default_ttl
- int
Tempo predefinito in tempo reale (TTL) per gli elementi nel contenitore. Se non specificato, gli elementi non scadono.
- offer_throughput
- Union[int, ThroughputProperties]
Velocità effettiva con provisioning per questa offerta.
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.
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.
create_user
Creare un nuovo utente nel contenitore.
Per aggiornare o sostituire un utente esistente, usare il <xref:ContainerProxy.upsert_user> metodo .
async create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxyParametri
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.
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:
await database.create_user(dict(id="Walter Harp"))
print("Created user 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.
async delete_container(container: str | ContainerProxy | Dict[str, Any], **kwargs: Any) -> NoneParametri
- container
- str oppure Dict[str, Any] oppure ContainerProxy
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.
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.
async delete_user(user: str | UserProxy | Dict[str, Any], **kwargs: Any) -> NoneParametri
ID (nome), dict che rappresenta le proprietà o UserProxy l'istanza dell'utente da eliminare.
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
ID (nome), dict che rappresenta le proprietà o ContainerProxy l'istanza del contenitore da ottenere.
Restituisce
Istanza containerProxy che rappresenta il contenitore.
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.
async get_throughput(**kwargs: Any) -> ThroughputPropertiesParametri
Oggetto chiamabile richiamato con i metadati della risposta.
Restituisce
ThroughputProperties per il database.
Tipo restituito
Eccezioni
Non esistono proprietà di velocità effettiva per il database o non è stato possibile recuperare le proprietà della velocità effettiva.
get_user_client
Ottenere un userProxy per un utente con l'ID specificato.
get_user_client(user: str | UserProxy | Dict[str, Any]) -> UserProxyParametri
ID (nome), dict che rappresenta le proprietà o UserProxy l'istanza dell'utente da ottenere.
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(**kwargs) -> 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.
Oggetto chiamabile richiamato con i metadati della risposta.
Restituisce
Oggetto AsyncItemPaged delle 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)
async for container in database.list_containers():
print("Container ID: {}".format(container['id']))
list_users
Elencare tutti gli utenti nel contenitore.
list_users(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]Parametri
- max_item_count
- int
Numero massimo di utenti da restituire nell'operazione di enumerazione.
Oggetto chiamabile richiamato con i metadati della risposta.
Restituisce
Oggetto AsyncItemPaged delle 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(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]Parametri
Matrice facoltativa di parametri per la query. Ogni parametro è un dict() con chiavi 'name' e 'value'.
- max_item_count
- int
Numero massimo di elementi da restituire nell'operazione di enumerazione.
- session_token
- str
Token da usare con coerenza della sessione.
Oggetto chiamabile richiamato con i metadati della risposta.
Restituisce
Oggetto AsyncItemPaged delle 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 | Dict[str, Any], **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]Parametri
Matrice facoltativa di parametri per la query. Ogni parametro è un dict() con chiavi 'name' e 'value'. Ignorato se non viene specificata alcuna query.
- max_item_count
- int
Numero massimo di utenti da restituire nell'operazione di enumerazione.
Oggetto chiamabile richiamato con i metadati della risposta.
Restituisce
Oggetto AsyncItemPaged delle proprietà utente (dict).
Tipo restituito
Eccezioni
La creazione del contenitore non è riuscita.
read
Leggere le proprietà del database.
async read(**kwargs: Any) -> Dict[str, Any]Parametri
- session_token
- str
Token da usare con coerenza della sessione.
Oggetto chiamabile richiamato con i metadati della risposta.
Restituisce
Oggetto dict che rappresenta le proprietà del database
Tipo restituito
Eccezioni
Se non è stato possibile recuperare il database specificato.
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.
async replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyParametri
ID (nome), che rappresenta le proprietà o ContainerProxy l'istanza del contenitore da sostituire.
- default_ttl
- int
Durata (TTL) predefinita per gli elementi nel contenitore. Se non specificato, gli elementi non scadono.
Criteri di risoluzione dei conflitti da applicare al contenitore.
- 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.
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)
await database.replace_container(container, partition_key=PartitionKey(path='/productName'), default_ttl=3600)
# Display the new TTL setting for the container
container_props = await 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.
Se non esiste già un oggetto ThroughputProperties per il database, viene generata un'eccezione.
async replace_throughput(throughput: int | ThroughputProperties, **kwargs: Any) -> ThroughputPropertiesParametri
Oggetto chiamabile richiamato con i metadati della risposta.
Restituisce
ThroughputProperties per il database, aggiornato con una nuova velocità effettiva.
Tipo restituito
Eccezioni
Non sono disponibili proprietà di velocità effettiva per il database o non è stato possibile aggiornare le proprietà della velocità effettiva.
replace_user
Sostituisce l'utente specificato, se presente nel contenitore.
async replace_user(user: str | UserProxy | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxyParametri
ID (nome), che rappresenta le proprietà o UserProxy l'istanza dell'utente da sostituire.
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.
async upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxyParametri
Oggetto simile a ct che rappresenta l'utente da aggiornare o inserire.
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