DatabaseProxy Klasse
Eine Schnittstelle für die Interaktion mit einer bestimmten Datenbank.
Diese Klasse sollte nicht direkt instanziiert werden. Verwenden Sie stattdessen die <xref:azure.cosmos.aio.cosmos_client.CosmosClient.get_database_client> -Methode, um eine vorhandene Datenbank abzurufen, oder die <xref:azure.cosmos.aio.cosmos_client.CosmosClient.create_database> -Methode, um eine neue Datenbank zu erstellen.
Eine Datenbank enthält einen oder mehrere Container, von denen jeder Elemente, gespeicherte Prozeduren, Trigger und benutzerdefinierte Funktionen enthalten kann.
Eine Datenbank kann auch über zugeordnete Benutzer verfügen, die jeweils mit einem Satz von Berechtigungen für den Zugriff auf bestimmte Container, gespeicherte Prozeduren, Trigger, benutzerdefinierte Funktionen oder Elemente konfiguriert sind.
Eine Azure Cosmos DB-SQL-API-Datenbank verfügt über die folgenden vom System generierten Eigenschaften. Diese Eigenschaften sind schreibgeschützt:
_rid: Die Ressourcen-ID.
_ts: Zeitpunkt der letzten Aktualisierung der Ressource. Der Wert ist ein Zeitstempel.
_self: Der eindeutige adressierbare URI für die Ressource.
_etag: Das Ressourcen-etag, das für die Steuerung der optimistischen Parallelität erforderlich ist.
_colls: Der adressierbare Pfad der Sammlungsressource.
_users: Der adressierbare Pfad der Benutzerressource.
- Vererbung
-
builtins.objectDatabaseProxy
Konstruktor
DatabaseProxy(client_connection: CosmosClientConnection, id: str, properties: Dict[str, Any] = None)Parameter
- client_connection
- <xref:azure.cosmos.aio.CosmosClientConnection>
Client, von dem diese Datenbank abgerufen wurde.
- properties
Variablen
- id
Die ID (Name) der Datenbank.
Methoden
| create_container |
Erstellen Sie einen neuen Container mit der angegebenen ID (Name). Wenn ein Container mit der angegebenen ID bereits vorhanden ist, wird ein CosmosResourceExistsError ausgelöst. |
| create_container_if_not_exists |
Erstellen Sie einen Container, falls er noch nicht vorhanden ist. Wenn der Container bereits vorhanden ist, werden die vorhandenen Einstellungen zurückgegeben. Hinweis: Sie überprüft oder aktualisiert die vorhandenen Containereinstellungen nicht oder bietet keinen Durchsatz, wenn sie sich von dem unterscheiden, was an die Methode übergeben wurde. |
| create_user |
Erstellen Sie einen neuen Benutzer im Container. Verwenden Sie die <xref:ContainerProxy.upsert_user> -Methode, um einen vorhandenen Benutzer zu aktualisieren oder zu ersetzen. |
| delete_container |
Löschen eines Containers. |
| delete_user |
Löschen Sie den angegebenen Benutzer aus dem Container. |
| get_container_client |
Ruft einen ContainerProxy für einen Container mit der angegebenen ID (Name) ab. |
| get_throughput |
Rufen Sie das ThroughputProperties-Objekt für diese Datenbank ab. Wenn für die Datenbank bereits keine ThroughputProperties vorhanden sind, wird eine Ausnahme ausgelöst. |
| get_user_client |
Rufen Sie einen UserProxy für einen Benutzer mit der angegebenen ID ab. |
| list_containers |
Listen Sie die Container in der Datenbank auf. |
| list_users |
Listet alle Benutzer im Container auf. |
| query_containers |
Listet die Eigenschaften für Container in der aktuellen Datenbank auf. |
| query_users |
Gibt alle Benutzer zurück, die der angegebenen Abfrage entsprechen. |
| read |
Lesen sie die Datenbankeigenschaften. |
| replace_container |
Setzen Sie die Eigenschaften des Containers zurück. Eigenschaftsänderungen werden sofort beibehalten. Alle nicht angegebenen Eigenschaften werden auf ihre Standardwerte zurückgesetzt. |
| replace_throughput |
Ersetzen Sie den Durchsatz auf Datenbankebene. Wenn für die Datenbank bereits keine ThroughputProperties vorhanden sind, wird eine Ausnahme ausgelöst. |
| replace_user |
Ersetzt den angegebenen Benutzer, wenn er im Container vorhanden ist. |
| upsert_user |
Fügen Sie den angegebenen Benutzer ein, oder aktualisieren Sie sie. Wenn der Benutzer bereits im Container vorhanden ist, wird er ersetzt. Wenn der Benutzer noch nicht vorhanden ist, wird er eingefügt. |
create_container
Erstellen Sie einen neuen Container mit der angegebenen ID (Name).
Wenn ein Container mit der angegebenen ID bereits vorhanden ist, wird ein CosmosResourceExistsError ausgelöst.
async create_container(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyParameter
- partition_key
- PartitionKey
Der Partitionsschlüssel, der für den Container verwendet werden soll.
- default_ttl
- int
Standardzeit (TTL) für Elemente im Container. Wenn nicht angegeben, laufen Elemente nicht ab.
- offer_throughput
- Union[int, ThroughputProperties]
Der bereitgestellte Durchsatz für dieses Angebot.
Die eindeutige Schlüsselrichtlinie, die auf den Container angewendet werden soll.
Die Konfliktlösungsrichtlinie, die auf den Container angewendet werden soll.
- session_token
- str
Token zur Verwendung mit Sitzungskonsistenz.
Anfängliche Header, die als Teil der Anforderung gesendet werden sollen.
- etag
- str
Ein ETag-Wert oder das Platzhalterzeichen (*). Wird verwendet, um zu überprüfen, ob sich die Ressource geändert hat, und handelt gemäß der Bedingung, die vom parameter match_condition angegeben wird.
- match_condition
- MatchConditions
Die Übereinstimmungsbedingung, die für das etag verwendet werden soll.
Ein aufrufbarer Aufruf, der mit den Antwortmetadaten aufgerufen wird.
- analytical_storage_ttl
- int
Analysespeicherzeit (Time to Live, TTL) für Elemente im Container. Der Wert None lässt den analytischen Speicher aus, und der Wert -1 aktiviert den analytischen Speicher ohne TTL. Beachten Sie, dass analytischer Speicher nur für Synapse Link aktivierte Konten aktiviert werden kann.
Gibt zurück
Ein ContainerProxy-instance, das den neuen Container darstellt.
Rückgabetyp
Ausnahmen
Fehler bei der Containererstellung.
Beispiele
Erstellen Sie einen Container mit Standardeinstellungen:
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)
Erstellen Sie einen Container mit bestimmten Einstellungen. in diesem Fall ein benutzerdefinierter Partitionsschlüssel:
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
Erstellen Sie einen Container, falls er noch nicht vorhanden ist.
Wenn der Container bereits vorhanden ist, werden die vorhandenen Einstellungen zurückgegeben. Hinweis: Sie überprüft oder aktualisiert die vorhandenen Containereinstellungen nicht oder bietet keinen Durchsatz, wenn sie sich von dem unterscheiden, was an die Methode übergeben wurde.
async create_container_if_not_exists(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyParameter
- partition_key
- PartitionKey
Der Partitionsschlüssel, der für den Container verwendet werden soll.
- default_ttl
- int
Standardzeit (TTL) für Elemente im Container. Wenn nicht angegeben, laufen Elemente nicht ab.
- offer_throughput
- Union[int, ThroughputProperties]
Der bereitgestellte Durchsatz für dieses Angebot.
Die eindeutige Schlüsselrichtlinie, die auf den Container angewendet werden soll.
Die Konfliktlösungsrichtlinie, die auf den Container angewendet werden soll.
- session_token
- str
Token zur Verwendung mit Sitzungskonsistenz.
Anfängliche Header, die als Teil der Anforderung gesendet werden sollen.
- etag
- str
Ein ETag-Wert oder das Platzhalterzeichen (*). Wird verwendet, um zu überprüfen, ob sich die Ressource geändert hat, und handelt gemäß der Bedingung, die vom parameter match_condition angegeben wird.
- match_condition
- MatchConditions
Die Übereinstimmungsbedingung, die für das etag verwendet werden soll.
Ein aufrufbarer Aufruf, der mit den Antwortmetadaten aufgerufen wird.
- analytical_storage_ttl
- int
Analysespeicherzeit (Time to Live, TTL) für Elemente im Container. Der Wert None lässt den analytischen Speicher aus, und der Wert -1 aktiviert den analytischen Speicher ohne TTL. Beachten Sie, dass analytischer Speicher nur für Synapse Link aktivierte Konten aktiviert werden kann.
Gibt zurück
Ein ContainerProxy-instance, das den neuen Container darstellt.
Rückgabetyp
Ausnahmen
Fehler bei der Containererstellung.
create_user
Erstellen Sie einen neuen Benutzer im Container.
Verwenden Sie die <xref:ContainerProxy.upsert_user> -Methode, um einen vorhandenen Benutzer zu aktualisieren oder zu ersetzen.
async create_user(body: Dict[str, Any], **kwargs: Any) -> UserProxyParameter
Ein dict-ähnliches Objekt mit einem ID-Schlüssel und einem Wert, der den zu erstellenden Benutzer darstellt. Die Benutzer-ID muss innerhalb der Datenbank eindeutig sein und nicht mehr als 255 Zeichen umfassen.
Ein aufrufbarer Aufruf, der mit den Antwortmetadaten aufgerufen wird.
Gibt zurück
Ein UserProxy-instance, der den neuen Benutzer darstellt.
Rückgabetyp
Ausnahmen
Wenn der angegebene Benutzer nicht erstellt werden konnte.
Beispiele
Erstellen eines Datenbankbenutzers:
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
Löschen eines Containers.
async delete_container(container: str | ContainerProxy | Dict[str, Any], **kwargs: Any) -> NoneParameter
- container
- str oder Dict[str, Any] oder ContainerProxy
Die ID (Name) des zu löschenden Containers. Sie können entweder die ID des zu löschenden Containers, ein ContainerProxy instance oder ein Diktat übergeben, das die Eigenschaften des Containers darstellt.
- session_token
- str
Token zur Verwendung mit Sitzungskonsistenz.
Anfängliche Header, die als Teil der Anforderung gesendet werden sollen.
- etag
- str
Ein ETag-Wert oder das Platzhalterzeichen (*). Wird verwendet, um zu überprüfen, ob sich die Ressource geändert hat, und handelt gemäß der Bedingung, die vom parameter match_condition angegeben wird.
- match_condition
- MatchConditions
Die Übereinstimmungsbedingung, die für das etag verwendet werden soll.
Ein aufrufbarer Aufruf, der mit den Antwortmetadaten aufgerufen wird.
Rückgabetyp
Ausnahmen
Wenn der Container nicht gelöscht werden konnte.
delete_user
Löschen Sie den angegebenen Benutzer aus dem Container.
async delete_user(user: str | UserProxy | Dict[str, Any], **kwargs: Any) -> NoneParameter
Die ID (Name), das Diktat, das die Eigenschaften oder UserProxy instance des zu löschenden Benutzers darstellt.
Ein aufrufbarer Aufruf, der mit den Antwortmetadaten aufgerufen wird.
Rückgabetyp
Ausnahmen
Der Benutzer wurde nicht erfolgreich gelöscht.
Der Benutzer ist nicht im Container vorhanden.
get_container_client
Ruft einen ContainerProxy für einen Container mit der angegebenen ID (Name) ab.
get_container_client(container: str | ContainerProxy | Dict[str, Any]) -> ContainerProxyParameter
Die ID (Name), das Diktat, das die Eigenschaften oder ContainerProxy instance des abzurufenden Containers darstellt.
Gibt zurück
Ein ContainerProxy-instance, der den Container darstellt.
Rückgabetyp
Ausnahmen
Fehler bei der Containererstellung.
Beispiele
Rufen Sie einen vorhandenen Container ab, und behandeln Sie bei Auftreten einen Fehler:
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
get_throughput
Rufen Sie das ThroughputProperties-Objekt für diese Datenbank ab.
Wenn für die Datenbank bereits keine ThroughputProperties vorhanden sind, wird eine Ausnahme ausgelöst.
async get_throughput(**kwargs: Any) -> ThroughputPropertiesParameter
Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.
Gibt zurück
ThroughputProperties für die Datenbank.
Rückgabetyp
Ausnahmen
Für die Datenbank sind keine Durchsatzeigenschaften vorhanden, oder die Durchsatzeigenschaften konnten nicht abgerufen werden.
get_user_client
Rufen Sie einen UserProxy für einen Benutzer mit der angegebenen ID ab.
get_user_client(user: str | UserProxy | Dict[str, Any]) -> UserProxyParameter
Die ID (Name), das Diktat, das die Eigenschaften darstellt, oder UserProxy instance des abzurufenden Benutzers.
Gibt zurück
Ein UserProxy-instance, der den abgerufenen Benutzer darstellt.
Rückgabetyp
Ausnahmen
Fehler bei der Containererstellung.
list_containers
Listen Sie die Container in der Datenbank auf.
list_containers(**kwargs) -> AsyncItemPaged[Dict[str, Any]]Parameter
- max_item_count
- int
Maximale Anzahl von Elementen, die im Enumerationsvorgang zurückgegeben werden sollen.
- session_token
- str
Token zur Verwendung mit Sitzungskonsistenz.
Anfängliche Header, die als Teil der Anforderung gesendet werden sollen.
Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.
Gibt zurück
Eine AsyncItemPaged von Containereigenschaften (dicts).
Rückgabetyp
Ausnahmen
Fehler bei der Containererstellung.
Beispiele
Auflisten aller Container in der Datenbank:
database = client.get_database_client(database_name)
async for container in database.list_containers():
print("Container ID: {}".format(container['id']))
list_users
Listet alle Benutzer im Container auf.
list_users(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]Parameter
- max_item_count
- int
Maximale Anzahl von Benutzern, die im Enumerationsvorgang zurückgegeben werden sollen.
Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.
Gibt zurück
Eine AsyncItemPaged von Benutzereigenschaften (dicts).
Rückgabetyp
Ausnahmen
Fehler bei der Containererstellung.
query_containers
Listet die Eigenschaften für Container in der aktuellen Datenbank auf.
query_containers(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]Parameter
Optionales Array von Parametern für die Abfrage. Jeder Parameter ist ein dict() mit den Schlüsseln "name" und "value".
- max_item_count
- int
Maximale Anzahl von Elementen, die im Enumerationsvorgang zurückgegeben werden sollen.
- session_token
- str
Token zur Verwendung mit Sitzungskonsistenz.
Anfängliche Header, die als Teil der Anforderung gesendet werden sollen.
Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.
Gibt zurück
Eine AsyncItemPaged von Containereigenschaften (dicts).
Rückgabetyp
Ausnahmen
Fehler bei der Containererstellung.
query_users
Gibt alle Benutzer zurück, die der angegebenen Abfrage entsprechen.
query_users(query: str | Dict[str, Any], **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]Parameter
Optionales Array von Parametern für die Abfrage. Jeder Parameter ist ein dict() mit den Schlüsseln "name" und "value". Wird ignoriert, wenn keine Abfrage bereitgestellt wird.
- max_item_count
- int
Maximale Anzahl von Benutzern, die im Enumerationsvorgang zurückgegeben werden sollen.
Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.
Gibt zurück
Eine AsyncItemPaged von Benutzereigenschaften (dicts).
Rückgabetyp
Ausnahmen
Fehler bei der Containererstellung.
read
Lesen sie die Datenbankeigenschaften.
async read(**kwargs: Any) -> Dict[str, Any]Parameter
- session_token
- str
Token zur Verwendung mit Sitzungskonsistenz.
Anfängliche Header, die als Teil der Anforderung gesendet werden sollen.
Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.
Gibt zurück
Ein Diktat, das die Datenbankeigenschaften darstellt
Rückgabetyp
Ausnahmen
Wenn die angegebene Datenbank nicht abgerufen werden konnte.
replace_container
Setzen Sie die Eigenschaften des Containers zurück.
Eigenschaftsänderungen werden sofort beibehalten. Alle nicht angegebenen Eigenschaften werden auf ihre Standardwerte zurückgesetzt.
async replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: PartitionKey, **kwargs: Any) -> ContainerProxyParameter
Die ID (Name), ein Diktat, das die Eigenschaften oder ContainerProxy instance des zu ersetzenden Containers darstellt.
- partition_key
- PartitionKey
Der Partitionsschlüssel, der für den Container verwendet werden soll.
- default_ttl
- int
Standardzeit (TTL) für Elemente im Container. Wenn sie nicht angegeben sind, laufen Elemente nicht ab.
Die Konfliktlösungsrichtlinie, die auf den Container angewendet werden soll.
- session_token
- str
Token zur Verwendung mit Sitzungskonsistenz.
- etag
- str
Ein ETag-Wert oder das Platzhalterzeichen (*). Wird verwendet, um zu überprüfen, ob sich die Ressource geändert hat, und handelt gemäß der Bedingung, die vom parameter match_condition angegeben wird.
- match_condition
- MatchConditions
Die Übereinstimmungsbedingung, die für das etag verwendet werden soll.
Anfängliche Header, die als Teil der Anforderung gesendet werden sollen.
Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.
- analytical_storage_ttl
- int
Gültigkeitsdauer des Analysespeichers für Elemente im Container. Der Wert None verlässt den analytischen Speicher, und der Wert -1 aktiviert den analytischen Speicher ohne Gültigkeitsdauer. Beachten Sie, dass analytischer Speicher nur für Synapse Link aktivierte Konten aktiviert werden kann.
Gibt zurück
Ein ContainerProxy-instance, der den Container nach Abschluss des Ersetzens darstellt.
Rückgabetyp
Ausnahmen
Wird ausgelöst, wenn der Container nicht ersetzt werden konnte. Dies schließt ein, wenn der Container mit der angegebenen ID nicht vorhanden ist.
Beispiele
Setzen Sie die TTL-Eigenschaft für einen Container zurück, und zeigen Sie die aktualisierten Eigenschaften an:
# 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
Ersetzen Sie den Durchsatz auf Datenbankebene.
Wenn für die Datenbank bereits keine ThroughputProperties vorhanden sind, wird eine Ausnahme ausgelöst.
async replace_throughput(throughput: int | ThroughputProperties, **kwargs: Any) -> ThroughputPropertiesParameter
Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.
Gibt zurück
ThroughputProperties für die Datenbank, aktualisiert mit neuem Durchsatz.
Rückgabetyp
Ausnahmen
Für die Datenbank sind keine Durchsatzeigenschaften vorhanden, oder die Durchsatzeigenschaften konnten nicht aktualisiert werden.
replace_user
Ersetzt den angegebenen Benutzer, wenn er im Container vorhanden ist.
async replace_user(user: str | UserProxy | Dict[str, Any], body: Dict[str, Any], **kwargs: Any) -> UserProxyParameter
Die ID (Name), ein Diktat, das die Eigenschaften oder UserProxy instance des zu ersetzenden Benutzers darstellt.
Ein diktierähnliches Objekt, das den zu ersetzenden Benutzer darstellt.
Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.
Gibt zurück
Ein UserProxy-instance, der den Benutzer nach dem Ersetzen darstellt.
Rückgabetyp
Ausnahmen
Wenn beim Ersetzen ein Fehler aufgetreten ist oder der Benutzer mit der angegebenen ID nicht vorhanden ist.
upsert_user
Fügen Sie den angegebenen Benutzer ein, oder aktualisieren Sie sie.
Wenn der Benutzer bereits im Container vorhanden ist, wird er ersetzt. Wenn der Benutzer noch nicht vorhanden ist, wird er eingefügt.
async upsert_user(body: Dict[str, Any], **kwargs: Any) -> UserProxyParameter
Ein diktierähnliches Objekt, das den zu aktualisierenden oder einzufügenden Benutzer darstellt.
Ein aufrufbarer, der mit den Antwortmetadaten aufgerufen wird.
Gibt zurück
Ein UserProxy-instance, der den benutzer mit upsertiertem Benutzer darstellt.
Rückgabetyp
Ausnahmen
Wenn der angegebene Benutzer nicht durch upsertiert werden konnte.
Azure SDK for Python