Sdílet prostřednictvím

DatabaseProxy Třída

  • Reference

Rozhraní pro interakci s konkrétní databází.

Tato třída by neměla být vytvořena přímo. Místo toho použijte metodu <xref:azure.cosmos.aio.cosmos_client.CosmosClient.get_database_client> k získání existující databáze nebo metodu <xref:azure.cosmos.aio.cosmos_client.CosmosClient.create_database> k vytvoření nové databáze.

Databáze obsahuje jeden nebo více kontejnerů, z nichž každý může obsahovat položky, uložené procedury, triggery a uživatelem definované funkce.

Databáze může mít také přidružené uživatele, z nichž každý má nakonfigurovanou sadu oprávnění pro přístup k určitým kontejnerům, uloženým procedurám, triggerům, uživatelem definovaným funkcím nebo položkám.

Databáze rozhraní SQL API služby Azure Cosmos DB má následující systémem generované vlastnosti. Tyto vlastnosti jsou jen pro čtení:

  • _rid: ID prostředku.

  • _ts: Kdy byl prostředek naposledy aktualizován. Hodnota je časové razítko.

  • _self: Jedinečný adresovatelný identifikátor URI prostředku.

  • _etag: Značka eTag prostředku vyžadovaná pro řízení optimistické souběžnosti.

  • _colls: Adresovatelná cesta k prostředku kolekcí.

  • _users: Adresovatelná cesta prostředku uživatele.

Dědičnost
builtins.object
DatabaseProxy

Konstruktor

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

Parametry

client_connection
<xref:azure.cosmos.aio.CosmosClientConnection>
Vyžadováno

Klient, ze kterého byla tato databáze načtena.

id
str
Vyžadováno

ID (název) databáze.

properties
výchozí hodnota: None

Proměnné

id

ID (název) databáze.

Metody

create_container

Vytvořte nový kontejner se zadaným ID (názvem).

Pokud kontejner s daným ID již existuje, vyvolá se chyba CosmosResourceExistsError.
create_container_if_not_exists

Vytvořte kontejner, pokud ještě neexistuje.

Pokud kontejner už existuje, vrátí se existující nastavení. Poznámka: Nekontroluje ani neaktualizuje stávající nastavení kontejneru ani nenabízí propustnost, pokud se liší od toho, co bylo předáno metodě.
create_user

Vytvořte v kontejneru nového uživatele.

Pokud chcete aktualizovat nebo nahradit existujícího uživatele, použijte metodu <xref:ContainerProxy.upsert_user> .
delete_container

Odstranění kontejneru
delete_user

Odstraňte zadaného uživatele z kontejneru.
get_container_client

Získejte parametr ContainerProxy pro kontejner se zadaným ID (názvem).
get_throughput

Získejte objekt ThroughputProperties pro tuto databázi.

Pokud pro databázi ještě neexistují žádné vlastnosti propustnosti, dojde k výjimce.
get_user_client

Získejte userProxy pro uživatele se zadaným ID.
list_containers

Vypište kontejnery v databázi.
list_users

Zobrazí seznam všech uživatelů v kontejneru.
query_containers

Vypíše vlastnosti kontejnerů v aktuální databázi.
query_users

Vrátí všechny uživatele odpovídající danému dotazu.
read

Přečtěte si vlastnosti databáze.
replace_container

Resetujte vlastnosti kontejneru.

Změny vlastností se zachovají okamžitě. Všechny vlastnosti, které nejsou zadané, se obnoví na výchozí hodnoty.
replace_throughput

Nahraďte propustnost na úrovni databáze.

Pokud pro databázi neexistují žádné vlastnosti propustnosti, vyvolá se výjimka.
replace_user

Nahradí zadaného uživatele, pokud v kontejneru existuje.
upsert_user

Vložte nebo aktualizujte zadaného uživatele.

Pokud uživatel už v kontejneru existuje, nahradí se. Pokud uživatel ještě neexistuje, vloží se.

create_container

Vytvořte nový kontejner se zadaným ID (názvem).

Pokud kontejner s daným ID již existuje, vyvolá se chyba CosmosResourceExistsError.

async create_container(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxy

Parametry

id
str
Vyžadováno

ID (název) kontejneru, který se má vytvořit.

partition_key
PartitionKey
Vyžadováno

Klíč oddílu, který se má použít pro kontejner.

indexing_policy
dict[str, str]

Zásady indexování, které se mají použít u kontejneru.

default_ttl
int

Výchozí hodnota TTL (Time to Live) pro položky v kontejneru Pokud není zadáno, platnost položek nevyprší.

offer_throughput
Union[int, ThroughputProperties]

Zřízená propustnost pro tuto nabídku

unique_key_policy
dict[str, str]

Zásady jedinečného klíče, které se mají použít u kontejneru.

conflict_resolution_policy
dict[str, str]

Zásady řešení konfliktů, které se použijí pro kontejner.

session_token
str

Token pro použití s konzistencí relace.

initial_headers
dict[str, str]

Počáteční hlavičky, které se mají odeslat jako součást požadavku.

etag
str

Hodnota ETag nebo zástupný znak (*). Slouží ke kontrole, jestli se prostředek změnil, a k akci podle podmínky určené parametrem match_condition .

match_condition
MatchConditions

Podmínka shody, která se použije u značky etag.

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

Volatelný vyvolán s metadaty odpovědi.

analytical_storage_ttl
int

Hodnota TTL (Time to Live) analytického úložiště pro položky v kontejneru Hodnota None ponechá analytické úložiště vypnuté a hodnota -1 zapne analytické úložiště bez hodnoty TTL. Upozorňujeme, že analytické úložiště je možné povolit pouze u účtů s povolenou Synapse Link.

Návraty

Instance ContainerProxy představující nový kontejner.

Návratový typ

ContainerProxy

Výjimky

CosmosHttpResponseError

Vytvoření kontejneru se nezdařilo.

Příklady

Vytvořte kontejner s výchozím nastavením:


           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)

Vytvoření kontejneru se specifickými nastaveními v tomto případě vlastní klíč oddílu:


           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

Vytvořte kontejner, pokud ještě neexistuje.

Pokud kontejner už existuje, vrátí se existující nastavení. Poznámka: Nekontroluje ani neaktualizuje stávající nastavení kontejneru ani nenabízí propustnost, pokud se liší od toho, co bylo předáno metodě.

async create_container_if_not_exists(id: str, partition_key: PartitionKey, **kwargs: Any) -> ContainerProxy

Parametry

id
str
Vyžadováno

ID (název) kontejneru, který se má vytvořit.

partition_key
PartitionKey
Vyžadováno

Klíč oddílu, který se má použít pro kontejner.

indexing_policy
dict[str, str]

Zásady indexování, které se mají použít u kontejneru.

default_ttl
int

Výchozí hodnota TTL (Time to Live) pro položky v kontejneru Pokud není zadáno, platnost položek nevyprší.

offer_throughput
Union[int, ThroughputProperties]

Zřízená propustnost pro tuto nabídku

unique_key_policy
dict[str, str]

Zásady jedinečného klíče, které se mají použít u kontejneru.

conflict_resolution_policy
dict[str, str]

Zásady řešení konfliktů, které se použijí pro kontejner.

session_token
str

Token pro použití s konzistencí relace.

initial_headers
dict[str, str]

Počáteční hlavičky, které se mají odeslat jako součást požadavku.

etag
str

Hodnota ETag nebo zástupný znak (*). Slouží ke kontrole, jestli se prostředek změnil, a k akci podle podmínky určené parametrem match_condition .

match_condition
MatchConditions

Podmínka shody, která se použije u značky etag.

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

Volatelný vyvolán s metadaty odpovědi.

analytical_storage_ttl
int

Hodnota TTL (Time to Live) analytického úložiště pro položky v kontejneru Hodnota None ponechá analytické úložiště vypnuté a hodnota -1 zapne analytické úložiště bez hodnoty TTL. Upozorňujeme, že analytické úložiště je možné povolit pouze u účtů s povolenou Synapse Link.

Návraty

Instance ContainerProxy představující nový kontejner.

Návratový typ

ContainerProxy

Výjimky

CosmosHttpResponseError

Vytvoření kontejneru se nezdařilo.

create_user

Vytvořte v kontejneru nového uživatele.

Pokud chcete aktualizovat nebo nahradit existujícího uživatele, použijte metodu <xref:ContainerProxy.upsert_user> .

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

Parametry

body
Dict[str, Any]
Vyžadováno

Objekt podobný diktování s klíčem ID a hodnotou představující uživatele, který se má vytvořit. ID uživatele musí být v rámci databáze jedinečné a nesmí obsahovat více než 255 znaků.

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

Volatelný vyvolán s metadaty odpovědi.

Návraty

Instance UserProxy představující nového uživatele.

Návratový typ

UserProxy

Výjimky

CosmosHttpResponseError

Pokud se daného uživatele nepodařilo vytvořit.

Příklady

Vytvoření uživatele databáze:


           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

Odstranění kontejneru

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

Parametry

container
str nebo Dict[str, Any] nebo ContainerProxy
Vyžadováno

ID (název) kontejneru, který se má odstranit. Můžete předat ID kontejneru, který se má odstranit, ContainerProxy instanci nebo dict představující vlastnosti kontejneru.

session_token
str

Token pro použití s konzistencí relace.

initial_headers
dict[str, str]

Počáteční hlavičky, které se mají odeslat jako součást požadavku.

etag
str

Hodnota ETag nebo zástupný znak (*). Slouží ke kontrole, jestli se prostředek změnil, a k akci podle podmínky určené parametrem match_condition .

match_condition
MatchConditions

Podmínka shody, která se použije u značky etag.

response_hook
Callable[[Dict[str, str], None], None]

Volatelný vyvolán s metadaty odpovědi.

Návratový typ

None

Výjimky

CosmosHttpResponseError

Pokud kontejner nejde odstranit.

delete_user

Odstraňte zadaného uživatele z kontejneru.

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

Parametry

user
Union[str, Dict[str, Any], UserProxy]
Vyžadováno

ID (název) představující vlastnosti nebo UserProxy instanci uživatele, který má být odstraněn.

response_hook
Callable[[Dict[str, str], None], None]

Volatelný vyvolán s metadaty odpovědi.

Návratový typ

None

Výjimky

CosmosHttpResponseError

Uživatel nebyl úspěšně odstraněn.

CosmosResourceNotFoundError

Uživatel v kontejneru neexistuje.

get_container_client

Získejte parametr ContainerProxy pro kontejner se zadaným ID (názvem).

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

Parametry

container
Union[str, Dict[str, Any], ContainerProxy]
Vyžadováno

ID (název), dict představující vlastnosti nebo ContainerProxy instanci kontejneru, který chcete získat.

Návraty

Instance ContainerProxy představující kontejner.

Návratový typ

ContainerProxy

Výjimky

CosmosHttpResponseError

Vytvoření kontejneru se nezdařilo.

Příklady

Získejte existující kontejner a vyřiďte selhání, pokud k tomu dojde:


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

get_throughput

Získejte objekt ThroughputProperties pro tuto databázi.

Pokud pro databázi ještě neexistují žádné vlastnosti propustnosti, dojde k výjimce.

async get_throughput(**kwargs: Any) -> ThroughputProperties

Parametry

response_hook
Callable[[Dict[str, str], List[Dict[str, Any]]], None]

Volatelný vyvolán s metadaty odpovědi.

Návraty

Vlastnosti propustnosti pro databázi.

Návratový typ

ThroughputProperties

Výjimky

CosmosHttpResponseError

Pro databázi neexistují žádné vlastnosti propustnosti nebo se vlastnosti propustnosti nepodařilo načíst.

get_user_client

Získejte userProxy pro uživatele se zadaným ID.

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

Parametry

user
Union[str, Dict[str, Any], UserProxy]
Vyžadováno

ID (název), dict představující vlastnosti nebo UserProxy instanci uživatele, který chcete získat.

Návraty

Instance UserProxy představující načteného uživatele.

Návratový typ

UserProxy

Výjimky

CosmosHttpResponseError

Vytvoření kontejneru se nezdařilo.

list_containers

Vypište kontejnery v databázi.

list_containers(**kwargs) -> AsyncItemPaged[Dict[str, Any]]

Parametry

max_item_count
int

Maximální počet položek, které mají být vráceny v operaci výčtu.

session_token
str

Token pro použití s konzistencí relace.

initial_headers
dict[str, str]

Počáteční hlavičky, které se mají odeslat jako součást požadavku.

response_hook
Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Volatelný vyvolán s metadaty odpovědi.

Návraty

AsyncItemPaged vlastností kontejneru (dicts).

Návratový typ

<xref:AsyncItemPaged>[Dict[str, Any]]

Výjimky

CosmosHttpResponseError

Vytvoření kontejneru se nezdařilo.

Příklady

Vypište všechny kontejnery v databázi:


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

list_users

Zobrazí seznam všech uživatelů v kontejneru.

list_users(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parametry

max_item_count
int

Maximální počet uživatelů, kteří mají být vráceni v operaci výčtu.

response_hook
Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Volatelný vyvolán s metadaty odpovědi.

Návraty

AsyncItemPaged uživatelských vlastností (dicts).

Návratový typ

<xref:AsyncItemPaged>[Dict[str, Any]]

Výjimky

CosmosHttpResponseError

Vytvoření kontejneru se nezdařilo.

query_containers

Vypíše vlastnosti kontejnerů v aktuální databázi.

query_containers(**kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parametry

query
Union[str, Dict[str, Any]]

Dotaz SQL služby Azure Cosmos DB, který se má spustit.

parameters
Optional[List[Dict[str, Any]]]

Volitelné pole parametrů dotazu Každý parametr je dict() s klíči name a value.

max_item_count
int

Maximální počet položek, které mají být vráceny v operaci výčtu.

session_token
str

Token pro použití s konzistencí relace.

initial_headers
dict[str, str]

Počáteční hlavičky, které se mají odeslat jako součást požadavku.

response_hook
Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Volatelný vyvolán s metadaty odpovědi.

Návraty

AsyncItemPaged vlastností kontejneru (dicts).

Návratový typ

<xref:AsyncItemPaged>[Dict[str, Any]]

Výjimky

CosmosHttpResponseError

Vytvoření kontejneru se nezdařilo.

query_users

Vrátí všechny uživatele odpovídající danému dotazu.

query_users(query: str | Dict[str, Any], **kwargs: Any) -> AsyncItemPaged[Dict[str, Any]]

Parametry

query
Union[str, Dict[str, Any]]
Vyžadováno

Dotaz SQL služby Azure Cosmos DB, který se má spustit.

parameters
Optional[List[Dict[str, Any]]]

Volitelné pole parametrů dotazu Každý parametr je dict() s klíči name a value. Pokud se nezadá žádný dotaz, ignoruje se.

max_item_count
int

Maximální počet uživatelů, kteří mají být vráceni v operaci výčtu.

response_hook
Callable[[Dict[str, str], <xref:AsyncItemPaged>[Dict[str, Any]]], None]

Volatelný vyvolán s metadaty odpovědi.

Návraty

AsyncItemPaged uživatelských vlastností (dicts).

Návratový typ

<xref:AsyncItemPaged>[Dict[str, Any]]

Výjimky

CosmosHttpResponseError

Vytvoření kontejneru se nezdařilo.

read

Přečtěte si vlastnosti databáze.

async read(**kwargs: Any) -> Dict[str, Any]

Parametry

session_token
str

Token pro použití s konzistencí relace.

initial_headers
dict[str, str]

Počáteční hlavičky, které se mají odeslat jako součást požadavku.

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

Volatelný vyvolán s metadaty odpovědi.

Návraty

Dict představující vlastnosti databáze

Návratový typ

Dict[str, Any]

Výjimky

CosmosHttpResponseError

Pokud se daná databáze nedá načíst.

replace_container

Resetujte vlastnosti kontejneru.

Změny vlastností se zachovají okamžitě. Všechny vlastnosti, které nejsou zadané, se obnoví na výchozí hodnoty.

async replace_container(container: str | ContainerProxy | Dict[str, Any], partition_key: PartitionKey, **kwargs: Any) -> ContainerProxy

Parametry

container
Union[str, Dict[str, Any], ContainerProxy]
Vyžadováno

ID (název) a dict představující vlastnosti nebo ContainerProxy instanci kontejneru, který se má nahradit.

partition_key
PartitionKey
Vyžadováno

Klíč oddílu, který se má použít pro kontejner.

indexing_policy
dict[str, str]

Zásady indexování, které se mají použít u kontejneru.

default_ttl
int

Výchozí hodnota TTL (Time to Live) pro položky v kontejneru Pokud není zadáno, platnost položek nevyprší.

conflict_resolution_policy
dict[str, str]

Zásady řešení konfliktů, které se použijí pro kontejner.

session_token
str

Token pro použití s konzistencí relace.

etag
str

Hodnota ETag nebo zástupný znak (*). Slouží ke kontrole, jestli se prostředek změnil, a k akci podle podmínky určené parametrem match_condition .

match_condition
MatchConditions

Podmínka shody, která se použije u značky etag.

initial_headers
dict[str, str]

Počáteční hlavičky, které se mají odeslat jako součást požadavku.

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

Volatelný vyvolán s metadaty odpovědi.

analytical_storage_ttl
int

Hodnota TTL (Time to Live) analytického úložiště pro položky v kontejneru Hodnota None ponechá analytické úložiště vypnuté a hodnota -1 zapne analytické úložiště bez hodnoty TTL. Upozorňujeme, že analytické úložiště je možné povolit pouze u účtů s povolenou Synapse Link.

Návraty

Instance ContainerProxy představující kontejner po dokončení nahrazení.

Návratový typ

ContainerProxy

Výjimky

CosmosHttpResponseError

Vyvoláno, pokud kontejner nejde nahradit. To zahrnuje i to, jestli kontejner se zadaným ID neexistuje.

Příklady

Resetujte vlastnost TTL kontejneru a zobrazte aktualizované vlastnosti:


           # 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

Nahraďte propustnost na úrovni databáze.

Pokud pro databázi neexistují žádné vlastnosti propustnosti, vyvolá se výjimka.

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

Parametry

throughput
Union[int, ThroughputProperties]
Vyžadováno

Propustnost, která se má nastavit.

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

Volatelný vyvolán s metadaty odpovědi.

Návraty

Vlastnosti propustnosti databáze aktualizované o novou propustnost

Návratový typ

ThroughputProperties

Výjimky

CosmosHttpResponseError

Pro databázi neexistují žádné vlastnosti propustnosti nebo se vlastnosti propustnosti nedají aktualizovat.

replace_user

Nahradí zadaného uživatele, pokud v kontejneru existuje.

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

Parametry

user
Union[str, Dict[str, Any], UserProxy]
Vyžadováno

ID (název) představující vlastnosti nebo UserProxy instanci uživatele, který má být nahrazen.

body
Dict[str, Any]
Vyžadováno

Objekt podobný diktování představujícího uživatele, který má být nahrazen.

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

Volatelný vyvolán s metadaty odpovědi.

Návraty

Instance UserProxy představující uživatele po nahrazení prošla.

Návratový typ

UserProxy

Výjimky

CosmosHttpResponseError

Pokud se nahrazení nezdařilo nebo uživatel s daným ID neexistuje.

upsert_user

Vložte nebo aktualizujte zadaného uživatele.

Pokud uživatel už v kontejneru existuje, nahradí se. Pokud uživatel ještě neexistuje, vloží se.

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

Parametry

body
Dict[str, Any]
Vyžadováno

Objekt podobný diktování představující uživatele, který má být aktualizován nebo vložen.

response_hook
Callable[[Dict[str, str], Dict[str, Any]], None]

Volatelný vyvolán s metadaty odpovědi.

Návraty

A UserProxy instance představující upserted uživatele.

Návratový typ

UserProxy

Výjimky

CosmosHttpResponseError

Pokud daný uživatel nemohl být upsertován.