Sdílet prostřednictvím


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

Výjimky

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

Výjimky

Č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

Výjimky

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

Výjimky

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

Výjimky

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

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

Výjimky

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

Výjimky

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

Výjimky

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

Výjimky

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

Výjimky

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

Výjimky

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

Výjimky

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

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

Výjimky

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

Výjimky

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

Výjimky

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

Výjimky

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

Výjimky

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