DatabaseProxy Třída

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:CosmosClient.get_database_client> .

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émově 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:ClientSession>

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 s daný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 již 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 do metody.
create_user	V kontejneru vytvořte 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 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, vyvolá se výjimka. :keyword Callable response_hook: Volatelné volání s metadaty odpovědi. :returns: PropustnostProperties pro databázi. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Pro kontejner neexistují žádné vlastnosti propustnosti nebo vlastnosti propustnosti nelze načíst.
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.
read_offer	Získejte objekt ThroughputProperties pro tuto databázi. Pokud pro databázi ještě neexistují žádné vlastnosti propustnosti, vyvolá se výjimka. :keyword Callable response_hook: Volatelné volání s metadaty odpovědi. :returns: PropustnostProperties pro databázi. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Pro kontejner neexistují žádné vlastnosti propustnosti nebo vlastnosti propustnosti nelze načíst.
replace_container	Resetujte vlastnosti kontejneru. Změny vlastností se zachovají okamžitě. Všechny nezadané vlastnosti se obnoví na výchozí hodnoty.
replace_throughput	Nahraďte propustnost na úrovni databáze.
replace_user	Nahradí zadaného uživatele, pokud existuje v kontejneru.
upsert_user	Vložte nebo aktualizujte zadaného uživatele. Pokud uživatel již v kontejneru existuje, nahradí se. Pokud uživatel ještě neexistuje, vloží se.

create_container

Vytvořte nový kontejner s daným ID (názvem).

Pokud kontejner s daným ID již existuje, vyvolá se chyba 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

Parametry

id

Vyžadováno

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

partition_key

Vyžadováno

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

indexing_policy

Vyžadováno

Zásady indexování, které se mají použít pro kontejner.

default_ttl

Vyžadováno

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

offer_throughput

int nebo <xref:azure.cosmos.ThroughputProperties.>

Vyžadováno

Zřízená propustnost pro tuto nabídku

unique_key_policy

Vyžadováno

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

conflict_resolution_policy

Vyžadováno

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

session_token

str

Token pro použití s konzistencí relací.

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

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

response_hook

Callable

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 jenom na Synapse Link povolených účtech.

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 = 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 = 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 již 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 do metody.

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

Parametry

id

Vyžadováno

ID (název) kontejneru ke čtení nebo vytvoření.

partition_key

Vyžadováno

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

indexing_policy

Vyžadováno

Zásady indexování, které se mají použít pro kontejner.

default_ttl

Vyžadováno

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

populate_query_metrics

Vyžadováno

Povolte v hlavičce odpovědi vracené metriky dotazů.

offer_throughput

Vyžadováno

Zřízená propustnost pro tuto nabídku

unique_key_policy

Vyžadováno

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

conflict_resolution_policy

Vyžadováno

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

session_token

str

Token pro použití s konzistencí relací.

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

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

response_hook

Callable

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 jenom na Synapse Link povolených účtech.

Návraty

Instance ContainerProxy představující kontejner.

Návratový typ

ContainerProxy

Výjimky

CosmosHttpResponseError

Čtení nebo vytvoření kontejneru se nezdařilo.

create_user

V kontejneru vytvořte nového uživatele.

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

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

Parametry

body

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

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

Odstranění kontejneru

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

Parametry

container

Vyžadováno

ID (název) kontejneru, který chcete odstranit. Můžete předat ID kontejneru, který chcete odstranit, <xref:azure.cosmos.database.ContainerProxy> instanci nebo diktát představující vlastnosti kontejneru.

session_token

str

Token pro použití s konzistencí relací.

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

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

response_hook

Callable

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.

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

Parametry

user

Vyžadováno

ID (název) – dikt představující vlastnosti nebo <xref:azure.cosmos.database.UserProxy> instanci uživatele, který má být odstraněn.

response_hook

Callable

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 ContainerProxy pro kontejner se zadaným ID (názvem).

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

Parametry

container

Vyžadováno

ID (název) kontejneru, <xref:azure.cosmos.database.ContainerProxy> instance nebo diktátu představující vlastnosti kontejneru, který se má načíst.

Návraty

Instance ContainerProxy představující načtenou databázi.

Návratový typ

ContainerProxy

Výjimky

CosmosHttpResponseError

Vytvoření kontejneru se nezdařilo.

Příklady

Získání existujícího kontejneru a zpracování selhání, pokud dojde k:

   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, vyvolá se výjimka. :keyword Callable response_hook: Volatelné volání s metadaty odpovědi. :returns: PropustnostProperties pro databázi. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Pro kontejner neexistují žádné vlastnosti propustnosti nebo

vlastnosti propustnosti nelze načíst.

get_throughput(**kwargs: Any) -> ThroughputProperties

Návratový typ

ThroughputProperties

Výjimky

CosmosHttpResponseError

Vytvoření kontejneru se nezdařilo.

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

Vyžadováno

ID (název) – dikt představující vlastnosti nebo <xref:azure.cosmos.database.UserProxy> instanci uživatele, který se má načíst.

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(max_item_count: int | None = None, populate_query_metrics: bool | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parametry

max_item_count

Vyžadováno

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

session_token

str

Token pro použití s konzistencí relací.

initial_headers

dict[str,str]

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

response_hook

Callable

Volatelné vyvolání s metadaty odpovědi.

Návraty

Iterable of container properties (dicts).

Návratový typ

Iterable[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)
   for container in database.list_containers():
       print("Container ID: {}".format(container['id']))

list_users

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

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

Parametry

max_item_count

Vyžadováno

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

response_hook

Callable

Volatelné vyvolání s metadaty odpovědi.

Návraty

Iterable of user properties (dicts).

Návratový typ

Iterable[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(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]]

Parametry

query

Vyžadováno

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

parameters

Vyžadováno

Volitelné pole parametrů dotazu. Ignorováno, pokud není zadaný žádný dotaz.

max_item_count

Vyžadováno

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

session_token

str

Token pro použití s konzistencí relací.

initial_headers

dict[str,str]

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

response_hook

Callable

Volatelné vyvolání s metadaty odpovědi.

Návraty

Iterable of container properties (dicts).

Návratový typ

Iterable[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, parameters: List[str] | None = None, max_item_count: int | None = None, **kwargs: Any) -> Iterable[Dict[str, Any]]

Parametry

query

Vyžadováno

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

parameters

Vyžadováno

Volitelné pole parametrů dotazu. Ignorováno, pokud není zadaný žádný dotaz.

max_item_count

Vyžadováno

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

response_hook

Callable

Volatelné vyvolání s metadaty odpovědi.

Návraty

Iterable of user properties (dicts).

Návratový typ

Iterable[str, Any]

Výjimky

CosmosHttpResponseError

Vytvoření kontejneru se nezdařilo.

read

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

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

Parametry

session_token

str

Token pro použití s konzistencí relací.

initial_headers

dict[str,str]

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

response_hook

Callable

Volatelné vyvolání s metadaty odpovědi.

Návratový typ

Dict[<xref:Str>, Any]

Výjimky

CosmosHttpResponseError

Pokud se danou databázi nepodařilo načíst.

read_offer

Získejte objekt ThroughputProperties pro tuto databázi. Pokud pro databázi ještě neexistují žádné vlastnosti propustnosti, vyvolá se výjimka. :keyword Callable response_hook: Volatelné volání s metadaty odpovědi. :returns: PropustnostProperties pro databázi. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: Pro kontejner neexistují žádné vlastnosti propustnosti nebo

vlastnosti propustnosti nelze načíst.

read_offer(**kwargs: Any) -> ThroughputProperties

Návratový typ

ThroughputProperties

Výjimky

CosmosHttpResponseError

Vytvoření kontejneru se nezdařilo.

replace_container

Resetujte vlastnosti kontejneru.

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

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

Parametry

container

Vyžadováno

ID (název) – dikt představující vlastnosti nebo <xref:azure.cosmos.database.ContainerProxy> instanci kontejneru, který má být nahrazen.

partition_key

Vyžadováno

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

indexing_policy

Vyžadováno

Zásady indexování, které se mají použít pro kontejner.

default_ttl

Vyžadováno

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

conflict_resolution_policy

Vyžadováno

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

populate_query_metrics

Vyžadováno

Povolte v hlavičce odpovědi vracené metriky dotazů.

session_token

str

Token pro použití s konzistencí relací.

etag

str

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

match_condition

MatchConditions

Podmínka shody, která se má použít 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

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 jenom na Synapse Link povolených účtech.

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 platí i v případě, že kontejner s daným ID neexistuje.

Příklady

Resetujte vlastnost TTL kontejneru a zobrazte aktualizované vlastnosti:

   # 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

Nahraďte propustnost na úrovni databáze.

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

Parametry

throughput

Vyžadováno

Propustnost, která se má nastavit (celé číslo).

response_hook

Callable

Volatelné vyvolání s metadaty odpovědi.

Návraty

Vlastnosti propustnosti databáze aktualizované o novou propustnost.

Návratový typ

ThroughputProperties

Výjimky

CosmosHttpResponseError

Pokud pro databázi neexistují žádné vlastnosti propustnosti nebo pokud se vlastnosti propustnosti nedají aktualizovat.

replace_user

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

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

Parametry

user

Vyžadováno

ID (název) – dikt představující vlastnosti nebo <xref:azure.cosmos.database.UserProxy> instanci uživatele, který má být nahrazen.

body

Vyžadováno

Objekt podobný diktování představující uživatele, který má nahradit.

response_hook

Callable

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 nahrazení selhalo nebo uživatel s daným ID neexistuje.

upsert_user

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

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

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

Parametry

body

Vyžadováno

Objekt podobný diktování, který představuje uživatele, který se má aktualizovat nebo vložit.

response_hook

Callable

Volatelné vyvolání s metadaty odpovědi.

Návraty

Instance UserProxy představující uživatele upserted.

Návratový typ

UserProxy

Výjimky

CosmosHttpResponseError

Pokud daný uživatel nemůže být upsertován.