Dela via


DatabaseProxy Klass

Ett gränssnitt för att interagera med en specifik databas.

Den här klassen ska inte instansieras direkt. Använd <xref:CosmosClient.get_database_client> i stället metoden .

En databas innehåller en eller flera containrar som var och en kan innehålla objekt, lagrade procedurer, utlösare och användardefinierade funktioner.

En databas kan också ha associerade användare, som var och en har konfigurerats med en uppsättning behörigheter för åtkomst till vissa containrar, lagrade procedurer, utlösare, användardefinierade funktioner eller objekt.

En Azure Cosmos DB SQL API-databas har följande systemgenererade egenskaper. Dessa egenskaper är skrivskyddade:

  • _rid: Resurs-ID.

  • _ts: När resursen senast uppdaterades. Värdet är en tidsstämpel.

  • _self: Resursens unika adresserbara URI.

  • _etag: Resursetaggar som krävs för optimistisk samtidighetskontroll.

  • _colls: Den adresserbara sökvägen för samlingsresursen.

  • _users: Den adresserbara sökvägen för användarresursen.

Arv
builtins.object
DatabaseProxy

Konstruktor

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

Parametrar

client_connection
<xref:ClientSession>
Obligatorisk

Klienten som den här databasen hämtades från.

id
str
Obligatorisk

ID (namn) för databasen.

properties
standardvärde: None

Variabler

id

Databasens ID (namn).

Metoder

create_container

Skapa en ny container med angivet ID (namn).

Om det redan finns en container med det angivna ID:t utlöses en CosmosResourceExistsError.

create_container_if_not_exists

Skapa en container om den inte redan finns.

Om containern redan finns returneras de befintliga inställningarna. Obs! Den kontrollerar eller uppdaterar inte de befintliga containerinställningarna eller erbjudandets dataflöde om de skiljer sig från vad som skickades till metoden.

create_user

Skapa en ny användare i containern.

Om du vill uppdatera eller ersätta en befintlig användare använder du <xref:ContainerProxy.upsert_user> metoden .

delete_container

Ta bort en container.

delete_user

Ta bort den angivna användaren från containern.

get_container_client

Hämta en ContainerProxy för en container med angivet ID (namn).

get_throughput

Hämta objektet ThroughputProperties för den här databasen. Om det inte redan finns några dataflödesegenskaper för databasen utlöses ett undantag. :keyword Callable response_hook: En anropbar som anropas med svarsmetadata. :returns: DataflödeEgenskaper för databasen. :genererar ~azure.cosmos.exceptions.CosmosHttpResponseError: Det finns inga dataflödesegenskaper för containern eller

Det gick inte att hämta dataflödesegenskaperna.

get_user_client

Hämta en UserProxy för en användare med angivet ID.

list_containers

Visa en lista över containrarna i databasen.

list_users

Visa en lista över alla användare i containern.

query_containers

Visa en lista över egenskaperna för containrar i den aktuella databasen.

query_users

Returnera alla användare som matchar den angivna frågan.

read

Läs databasegenskaperna.

read_offer

Hämta objektet ThroughputProperties för den här databasen. Om det inte redan finns några dataflödesegenskaper för databasen utlöses ett undantag. :keyword Callable response_hook: En anropbar som anropas med svarsmetadata. :returns: DataflödeEgenskaper för databasen. :genererar ~azure.cosmos.exceptions.CosmosHttpResponseError: Det finns inga dataflödesegenskaper för containern eller

Det gick inte att hämta dataflödesegenskaperna.

replace_container

Återställ egenskaperna för containern.

Egenskapsändringar sparas omedelbart. Alla egenskaper som inte anges återställs till standardvärdena.

replace_throughput

Ersätt dataflödet på databasnivå.

replace_user

Ersätter den angivna användaren om den finns i containern.

upsert_user

Infoga eller uppdatera den angivna användaren.

Om användaren redan finns i containern ersätts den. Om användaren inte redan finns infogas den.

create_container

Skapa en ny container med angivet ID (namn).

Om det redan finns en container med det angivna ID:t utlöses en 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

Parametrar

id
Obligatorisk

ID (namn) för container som ska skapas.

partition_key
Obligatorisk

Partitionsnyckeln som ska användas för containern.

indexing_policy
Obligatorisk

Indexeringsprincipen som ska tillämpas på containern.

default_ttl
Obligatorisk

Standard time to live (TTL) för objekt i containern. Om det är ospecificerat upphör objekten inte att gälla.

offer_throughput
int eller <xref:azure.cosmos.ThroughputProperties.>
Obligatorisk

Det etablerade dataflödet för det här erbjudandet.

unique_key_policy
Obligatorisk

Den unika nyckelprincip som ska tillämpas på containern.

conflict_resolution_policy
Obligatorisk

Konfliktlösningsprincipen som ska tillämpas på containern.

session_token
str

Token för användning med sessionskonsekvens.

initial_headers
dict[str,str]

Inledande huvuden som ska skickas som en del av begäran.

etag
str

Ett ETag-värde eller jokertecknet (*). Används för att kontrollera om resursen har ändrats och agera enligt villkoret som anges av parametern match_condition .

match_condition
MatchConditions

Matchningsvillkoret som ska användas på etag.

response_hook
Callable

En anropsbar anropas med svarsmetadata.

analytical_storage_ttl
int

TTL (Time to Live) för analysarkiv för objekt i containern. Värdet Ingen lämnar analyslagringen av och värdet -1 aktiverar analyslagring utan TTL. Observera att analyslagring endast kan aktiveras på Synapse Link aktiverade konton.

Returer

En ContainerProxy-instans som representerar den nya containern.

Returtyp

Undantag

Det gick inte att skapa containern.

Exempel

Skapa en container med standardinställningar:


   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)

Skapa en container med specifika inställningar; I det här fallet en anpassad partitionsnyckel:


   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

Skapa en container om den inte redan finns.

Om containern redan finns returneras de befintliga inställningarna. Obs! Den kontrollerar eller uppdaterar inte de befintliga containerinställningarna eller erbjudandets dataflöde om de skiljer sig från vad som skickades till metoden.

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

Parametrar

id
Obligatorisk

ID (namn) för container som ska läsas eller skapas.

partition_key
Obligatorisk

Partitionsnyckeln som ska användas för containern.

indexing_policy
Obligatorisk

Indexeringsprincipen som ska tillämpas på containern.

default_ttl
Obligatorisk

Standard time to live (TTL) för objekt i containern. Om det är ospecificerat upphör objekten inte att gälla.

populate_query_metrics
Obligatorisk

Aktivera returnerade frågemått i svarshuvuden.

offer_throughput
Obligatorisk

Det etablerade dataflödet för det här erbjudandet.

unique_key_policy
Obligatorisk

Den unika nyckelprincip som ska tillämpas på containern.

conflict_resolution_policy
Obligatorisk

Konfliktlösningsprincipen som ska tillämpas på containern.

session_token
str

Token för användning med sessionskonsekvens.

initial_headers
dict[str,str]

Inledande huvuden som ska skickas som en del av begäran.

etag
str

Ett ETag-värde eller jokertecknet (*). Används för att kontrollera om resursen har ändrats och agera enligt villkoret som anges av parametern match_condition .

match_condition
MatchConditions

Matchningsvillkoret som ska användas på etag.

response_hook
Callable

En anropsbar anropas med svarsmetadata.

analytical_storage_ttl
int

TTL (Time to Live) för analysarkiv för objekt i containern. Värdet Ingen lämnar analyslagringen av och värdet -1 aktiverar analyslagring utan TTL. Observera att analyslagring endast kan aktiveras på Synapse Link aktiverade konton.

Returer

En ContainerProxy-instans som representerar containern.

Returtyp

Undantag

Det gick inte att läsa eller skapa containern.

create_user

Skapa en ny användare i containern.

Om du vill uppdatera eller ersätta en befintlig användare använder du <xref:ContainerProxy.upsert_user> metoden .

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

Parametrar

body
Obligatorisk

Ett dict-liknande objekt med en ID-nyckel och ett värde som representerar den användare som ska skapas. Användar-ID:t måste vara unikt i databasen och bestå av högst 255 tecken.

response_hook
Callable

En anropsbar anropas med svarsmetadata.

Returer

En UserProxy-instans som representerar den nya användaren.

Returtyp

Undantag

Om det inte gick att skapa den angivna användaren.

Exempel

Skapa en databasanvändare:


   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

Ta bort en container.

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

Parametrar

container
Obligatorisk

ID :t (namn) för containern som ska tas bort. Du kan antingen skicka ID:t för containern som ska tas bort, en <xref:azure.cosmos.database.ContainerProxy> instans eller en diktamen som representerar containerns egenskaper.

session_token
str

Token för användning med sessionskonsekvens.

initial_headers
dict[str,str]

Inledande huvuden som ska skickas som en del av begäran.

etag
str

Ett ETag-värde eller jokertecknet (*). Används för att kontrollera om resursen har ändrats och agera enligt villkoret som anges av parametern match_condition .

match_condition
MatchConditions

Matchningsvillkoret som ska användas på etag.

response_hook
Callable

En anropsbar anropas med svarsmetadata.

Returtyp

Undantag

Om det inte gick att ta bort containern.

delete_user

Ta bort den angivna användaren från containern.

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

Parametrar

user
Obligatorisk

ID :t (namn), diktamen som representerar egenskaperna eller <xref:azure.cosmos.database.UserProxy> instansen av den användare som ska tas bort.

response_hook
Callable

En anropsbar anropad med svarsmetadata.

Returtyp

Undantag

Användaren har inte tagits bort.

Användaren finns inte i containern.

get_container_client

Hämta en ContainerProxy för en container med angivet ID (namn).

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

Parametrar

container
Obligatorisk

ID:t (namn) för containern, en <xref:azure.cosmos.database.ContainerProxy> instans eller en diktamen som representerar egenskaperna för containern som ska hämtas.

Returer

En ContainerProxy-instans som representerar den hämtade databasen.

Returtyp

Undantag

Det gick inte att skapa containern.

Exempel

Hämta en befintlig container, hantera ett fel om det påträffas:


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

get_throughput

Hämta objektet ThroughputProperties för den här databasen. Om det inte redan finns några dataflödesegenskaper för databasen utlöses ett undantag. :keyword Callable response_hook: En anropbar som anropas med svarsmetadata. :returns: DataflödeEgenskaper för databasen. :genererar ~azure.cosmos.exceptions.CosmosHttpResponseError: Det finns inga dataflödesegenskaper för containern eller

Det gick inte att hämta dataflödesegenskaperna.

get_throughput(**kwargs: Any) -> ThroughputProperties

Returtyp

Undantag

Det gick inte att skapa containern.

get_user_client

Hämta en UserProxy för en användare med angivet ID.

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

Parametrar

user
Obligatorisk

ID :t (namn), diktat som representerar egenskaperna eller <xref:azure.cosmos.database.UserProxy> instansen för den användare som ska hämtas.

Returer

En UserProxy-instans som representerar den hämtade användaren.

Returtyp

Undantag

Det gick inte att skapa containern.

list_containers

Visa en lista över containrarna i databasen.

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

Parametrar

max_item_count
Obligatorisk

Maximalt antal objekt som ska returneras i uppräkningsåtgärden.

session_token
str

Token för användning med sessionskonsekvens.

initial_headers
dict[str,str]

Inledande rubriker som ska skickas som en del av begäran.

response_hook
Callable

En anropsbar anropad med svarsmetadata.

Returer

En iterabel av containeregenskaper (dikteringar).

Returtyp

Undantag

Det gick inte att skapa containern.

Exempel

Visa en lista över alla containrar i databasen:


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

list_users

Visa en lista över alla användare i containern.

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

Parametrar

max_item_count
Obligatorisk

Maximalt antal användare som ska returneras i uppräkningsåtgärden.

response_hook
Callable

En anropsbar anropad med svarsmetadata.

Returer

En iterabel av användaregenskaper (dikteringar).

Returtyp

Undantag

Det gick inte att skapa containern.

query_containers

Visa en lista över egenskaperna för containrar i den aktuella databasen.

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]]

Parametrar

query
Obligatorisk

Azure Cosmos DB SQL-frågan som ska köras.

parameters
Obligatorisk

Valfri matris med parametrar i frågan. Ignoreras om ingen fråga har angetts.

max_item_count
Obligatorisk

Maximalt antal objekt som ska returneras i uppräkningsåtgärden.

session_token
str

Token för användning med sessionskonsekvens.

initial_headers
dict[str,str]

Inledande rubriker som ska skickas som en del av begäran.

response_hook
Callable

En anropsbar anropad med svarsmetadata.

Returer

En iterabel av containeregenskaper (dikteringar).

Returtyp

Undantag

Det gick inte att skapa containern.

query_users

Returnera alla användare som matchar den angivna frågan.

query_users(query: str, parameters: List[str] | None = None, max_item_count: int | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parametrar

query
Obligatorisk

Azure Cosmos DB SQL-frågan som ska köras.

parameters
Obligatorisk

Valfri matris med parametrar i frågan. Ignoreras om ingen fråga har angetts.

max_item_count
Obligatorisk

Maximalt antal användare som ska returneras i uppräkningsåtgärden.

response_hook
Callable

En anropsbar anropad med svarsmetadata.

Returer

En iterabel av användaregenskaper (dikteringar).

Returtyp

Undantag

Det gick inte att skapa containern.

read

Läs databasegenskaperna.

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

Parametrar

session_token
str

Token för användning med sessionskonsekvens.

initial_headers
dict[str,str]

Inledande rubriker som ska skickas som en del av begäran.

response_hook
Callable

En anropsbar anropad med svarsmetadata.

Returtyp

Dict[<xref:Str>, Any]

Undantag

Om den angivna databasen inte kunde hämtas.

read_offer

Hämta objektet ThroughputProperties för den här databasen. Om det inte redan finns några dataflödesegenskaper för databasen utlöses ett undantag. :keyword Callable response_hook: En anropbar som anropas med svarsmetadata. :returns: DataflödeEgenskaper för databasen. :genererar ~azure.cosmos.exceptions.CosmosHttpResponseError: Det finns inga dataflödesegenskaper för containern eller

Det gick inte att hämta dataflödesegenskaperna.

read_offer(**kwargs: Any) -> ThroughputProperties

Returtyp

Undantag

Det gick inte att skapa containern.

replace_container

Återställ egenskaperna för containern.

Egenskapsändringar sparas omedelbart. Alla egenskaper som inte anges återställs till standardvärdena.

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

Parametrar

container
Obligatorisk

ID:t (namn), diktamen som representerar egenskaperna eller <xref:azure.cosmos.database.ContainerProxy> instansen av containern som ska ersättas.

partition_key
Obligatorisk

Partitionsnyckeln som ska användas för containern.

indexing_policy
Obligatorisk

Indexeringsprincipen som ska tillämpas på containern.

default_ttl
Obligatorisk

Standardtid att leva (TTL) för objekt i containern. Om objekten är ospecificerade upphör de inte att gälla.

conflict_resolution_policy
Obligatorisk

Konfliktlösningsprincipen som ska tillämpas på containern.

populate_query_metrics
Obligatorisk

Aktivera returnerade frågemått i svarshuvuden.

session_token
str

Token för användning med sessionskonsekvens.

etag
str

Ett ETag-värde eller jokertecknet (*). Används för att kontrollera om resursen har ändrats och agera enligt villkoret som anges av parametern match_condition .

match_condition
MatchConditions

Matchningsvillkoret som ska användas på etag.

initial_headers
dict[str,str]

Inledande rubriker som ska skickas som en del av begäran.

response_hook
Callable

En anropsbar anropad med svarsmetadata.

analytical_storage_ttl
int

TTL (Analytical Store Time to Live) för objekt i containern. Värdet None lämnar analyslagringen inaktiverad och värdet -1 aktiverar analyslagring utan TTL. Observera att analyslagring endast kan aktiveras på Synapse Link aktiverade konton.

Returer

En ContainerProxy-instans som representerar containern efter att ersättningen har slutförts.

Returtyp

Undantag

Upphöjt om containern inte kunde ersättas. Detta inkluderar om containern med angivet ID inte finns.

Exempel

Återställ TTL-egenskapen i en container och visa de uppdaterade egenskaperna:


   # 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

Ersätt dataflödet på databasnivå.

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

Parametrar

throughput
Obligatorisk

Det dataflöde som ska anges (ett heltal).

response_hook
Callable

En anropsbar anropad med svarsmetadata.

Returer

DataflödeEgenskaper för databasen, uppdaterade med nytt dataflöde.

Returtyp

Undantag

Om det inte finns några dataflödesegenskaper för databasen eller om dataflödesegenskaperna inte kunde uppdateras.

replace_user

Ersätter den angivna användaren om den finns i containern.

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

Parametrar

user
Obligatorisk

ID:t (namn), diktat som representerar egenskaperna eller <xref:azure.cosmos.database.UserProxy> instansen för den användare som ska ersättas.

body
Obligatorisk

Ett diktaliknande objekt som representerar användaren som ska ersättas.

response_hook
Callable

En anropsbar anropad med svarsmetadata.

Returer

En UserProxy-instans som representerar användaren efter ersättningen gick igenom.

Returtyp

Undantag

Om ersättningen misslyckades eller om användaren med angivet ID inte finns.

upsert_user

Infoga eller uppdatera den angivna användaren.

Om användaren redan finns i containern ersätts den. Om användaren inte redan finns infogas den.

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

Parametrar

body
Obligatorisk

Ett diktaliknande objekt som representerar användaren att uppdatera eller infoga.

response_hook
Callable

En anropsbar anropad med svarsmetadata.

Returer

En UserProxy-instans som representerar den upserted användaren.

Returtyp

Undantag

Om den angivna användaren inte kunde upserted.