Share via

DatabaseProxy Класс

  • Ссылка

Интерфейс для взаимодействия с определенной базой данных.

Экземпляр этого класса не следует создавать напрямую. Вместо этого используйте <xref:CosmosClient.get_database_client> метод .

База данных содержит один или несколько контейнеров, каждый из которых может содержать элементы, хранимые процедуры, триггеры и определяемые пользователем функции.

База данных также может иметь связанных пользователей, каждый из которых настроен с набором разрешений на доступ к определенным контейнерам, хранимым процедурам, триггерам, определяемым пользователем функциям или элементам.

База данных API SQL Azure Cosmos DB имеет следующие системные свойства. Эти свойства доступны только для чтения:

  • _rid: идентификатор ресурса.

  • _ts: время последнего обновления ресурса. Значение — метка времени.

  • _self: уникальный адресируемый URI для ресурса.

  • _etag: тег ресурса, необходимый для управления оптимистическим параллелизмом.

  • _colls: адресируемый путь к ресурсу коллекций.

  • _users: адресируемый путь к ресурсу пользователей.

Наследование
builtins.object
DatabaseProxy

Конструктор

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

Параметры

client_connection
<xref:ClientSession>
Обязательно

Клиент, из которого была получена эта база данных.

id
str
Обязательно

Идентификатор (имя) базы данных.

properties
значение по умолчанию: None

Переменные

id

Идентификатор (имя) базы данных.

Методы

create_container

Создайте контейнер с заданным идентификатором (именем).

Если контейнер с указанным идентификатором уже существует, возникает cosmosResourceExistsError.
create_container_if_not_exists

Создайте контейнер, если он еще не существует.

Если контейнер уже существует, возвращаются существующие параметры. Примечание. Он не проверка или не обновляет существующие параметры контейнера или предлагает пропускную способность, если они отличаются от того, что было передано в метод.
create_user

Создайте пользователя в контейнере.

Чтобы обновить или заменить существующего пользователя, используйте <xref:ContainerProxy.upsert_user> метод .
delete_container

Удаление контейнера.
delete_user

Удалите указанного пользователя из контейнера.
get_container_client

Получение ContainerProxy для контейнера с указанным идентификатором (именем).
get_throughput

Получите объект ThroughputProperties для этой базы данных. Если свойства ThroughputProperties для базы данных еще не существуют, возникает исключение. :ключевое слово Вызываемый response_hook: вызываемый объект с метаданными ответа. :returns: ThroughputProperties для базы данных. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: свойства пропускной способности для контейнера или

Не удалось получить свойства пропускной способности.
get_user_client

Получите UserProxy для пользователя с указанным идентификатором.
list_containers

Вывод списка контейнеров в базе данных.
list_users

Вывод списка всех пользователей в контейнере.
query_containers

Список свойств контейнеров в текущей базе данных.
query_users

Возвращает всех пользователей, соответствующих заданному запросу.
read

Чтение свойств базы данных.
read_offer

Получите объект ThroughputProperties для этой базы данных. Если свойства ThroughputProperties для базы данных еще не существуют, возникает исключение. :ключевое слово Вызываемый response_hook: вызываемый объект с метаданными ответа. :returns: ThroughputProperties для базы данных. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: свойства пропускной способности для контейнера или

Не удалось получить свойства пропускной способности.
replace_container

Сбросьте свойства контейнера.

Изменения свойств сохраняются немедленно. Все не указанные свойства будут сброшены до значений по умолчанию.
replace_throughput

Замените пропускную способность на уровне базы данных.
replace_user

Заменяет указанного пользователя, если он существует в контейнере.
upsert_user

Вставьте или обновите указанного пользователя.

Если пользователь уже существует в контейнере, он заменяется. Если пользователь еще не существует, он вставляется.

create_container

Создайте контейнер с заданным идентификатором (именем).

Если контейнер с указанным идентификатором уже существует, возникает 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

Параметры

id
Обязательно

Идентификатор (имя) создаваемого контейнера.

partition_key
Обязательно

Ключ секции, используемый для контейнера.

indexing_policy
Обязательно

Политика индексирования, применяемая к контейнеру.

default_ttl
Обязательно

Срок жизни (TTL) по умолчанию для элементов в контейнере. Если это не указано, срок действия элементов не истекает.

offer_throughput
int или <xref:azure.cosmos.ThroughputProperties.>
Обязательно

Подготовленная пропускная способность для этого предложения.

unique_key_policy
Обязательно

Политика уникального ключа, применяемая к контейнеру.

conflict_resolution_policy
Обязательно

Политика разрешения конфликтов, применяемая к контейнеру.

session_token
str

Маркер для использования с согласованностью сеанса.

initial_headers
dict[str,str]

Начальные заголовки, отправляемые в составе запроса.

etag
str

Значение ETag или подстановочный знак (*). Используется для проверка, если ресурс изменился, и действует в соответствии с условием, заданным параметром match_condition.

match_condition
MatchConditions

Условие соответствия, используемое для etag.

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

analytical_storage_ttl
int

Срок жизни аналитического хранилища (TTL) для элементов в контейнере. Значение None оставляет аналитическое хранилище отключенным, а значение -1 включает аналитическое хранилище без срока жизни. Обратите внимание, что аналитическое хранилище можно включить только в учетных записях с поддержкой Synapse Link.

Возвращаемое значение

Экземпляр ContainerProxy , представляющий новый контейнер.

Возвращаемый тип

ContainerProxy

Исключения

CosmosHttpResponseError

Не удалось создать контейнер.

Примеры

Создайте контейнер с параметрами по умолчанию:


   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)

Создание контейнера с определенными параметрами; в этом случае пользовательский ключ секции:


   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

Создайте контейнер, если он еще не существует.

Если контейнер уже существует, возвращаются существующие параметры. Примечание. Он не проверка или не обновляет существующие параметры контейнера или предлагает пропускную способность, если они отличаются от того, что было передано в метод.

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

Параметры

id
Обязательно

Идентификатор (имя) контейнера для чтения или создания.

partition_key
Обязательно

Ключ секции, используемый для контейнера.

indexing_policy
Обязательно

Политика индексирования, применяемая к контейнеру.

default_ttl
Обязательно

Срок жизни (TTL) по умолчанию для элементов в контейнере. Если это не указано, срок действия элементов не истекает.

populate_query_metrics
Обязательно

Включите возвращаемые метрики запросов в заголовках ответов.

offer_throughput
Обязательно

Подготовленная пропускная способность для этого предложения.

unique_key_policy
Обязательно

Политика уникального ключа, применяемая к контейнеру.

conflict_resolution_policy
Обязательно

Политика разрешения конфликтов, применяемая к контейнеру.

session_token
str

Маркер для использования с согласованностью сеанса.

initial_headers
dict[str,str]

Начальные заголовки, отправляемые в составе запроса.

etag
str

Значение ETag или подстановочный знак (*). Используется для проверка, если ресурс изменился, и действует в соответствии с условием, заданным параметром match_condition.

match_condition
MatchConditions

Условие соответствия, используемое для etag.

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

analytical_storage_ttl
int

Срок жизни аналитического хранилища (TTL) для элементов в контейнере. Значение None оставляет аналитическое хранилище отключенным, а значение -1 включает аналитическое хранилище без срока жизни. Обратите внимание, что аналитическое хранилище можно включить только в учетных записях с поддержкой Synapse Link.

Возвращаемое значение

Экземпляр ContainerProxy , представляющий контейнер.

Возвращаемый тип

ContainerProxy

Исключения

CosmosHttpResponseError

Сбой чтения или создания контейнера.

create_user

Создайте пользователя в контейнере.

Чтобы обновить или заменить существующего пользователя, используйте <xref:ContainerProxy.upsert_user> метод .

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

Параметры

body
Обязательно

Объект, похожий на диктовку, с ключом идентификатора и значением, представляющим создаваемого пользователя. Идентификатор пользователя должен быть уникальным в пределах базы данных и содержать не более 255 символов.

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

Возвращаемое значение

Экземпляр UserProxy , представляющий нового пользователя.

Возвращаемый тип

UserProxy

Исключения

CosmosHttpResponseError

Если не удалось создать заданного пользователя.

Примеры

Создайте пользователя базы данных:


   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

Удаление контейнера.

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

Параметры

container
Обязательно

Идентификатор (имя) удаляемого контейнера. Вы можете передать идентификатор удаляемого контейнера, <xref:azure.cosmos.database.ContainerProxy> экземпляр или словарь, представляющий свойства контейнера.

session_token
str

Маркер для использования с согласованностью сеанса.

initial_headers
dict[str,str]

Начальные заголовки, отправляемые в составе запроса.

etag
str

Значение ETag или подстановочный знак (*). Используется для проверка, если ресурс изменился, и действует в соответствии с условием, заданным параметром match_condition.

match_condition
MatchConditions

Условие соответствия, используемое для etag.

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

Возвращаемый тип

None

Исключения

CosmosHttpResponseError

Если контейнер не удалось удалить.

delete_user

Удалите указанного пользователя из контейнера.

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

Параметры

user
Обязательно

Идентификатор (имя), дикт, представляющий свойства или <xref:azure.cosmos.database.UserProxy> экземпляр удаляемого пользователя.

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

Возвращаемый тип

None

Исключения

CosmosHttpResponseError

Пользователь не был успешно удален.

CosmosResourceNotFoundError

Пользователь не существует в контейнере.

get_container_client

Получение ContainerProxy для контейнера с указанным идентификатором (именем).

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

Параметры

container
Обязательно

Идентификатор (имя) контейнера, экземпляра <xref:azure.cosmos.database.ContainerProxy> или дикта, представляющего свойства извлекаемого контейнера.

Возвращаемое значение

Экземпляр ContainerProxy , представляющий полученную базу данных.

Возвращаемый тип

ContainerProxy

Исключения

CosmosHttpResponseError

Не удалось создать контейнер.

Примеры

Получите существующий контейнер, обрабатывающий сбой при обнаружении:


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

get_throughput

Получите объект ThroughputProperties для этой базы данных. Если свойства ThroughputProperties для базы данных еще не существуют, возникает исключение. :ключевое слово Вызываемый response_hook: вызываемый объект с метаданными ответа. :returns: ThroughputProperties для базы данных. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: свойства пропускной способности для контейнера или

Не удалось получить свойства пропускной способности.

get_throughput(**kwargs: Any) -> ThroughputProperties

Возвращаемый тип

ThroughputProperties

Исключения

CosmosHttpResponseError

Не удалось создать контейнер.

get_user_client

Получите UserProxy для пользователя с указанным идентификатором.

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

Параметры

user
Обязательно

Идентификатор (имя), дикт, представляющий извлекаемые свойства или <xref:azure.cosmos.database.UserProxy> экземпляр пользователя.

Возвращаемое значение

Экземпляр UserProxy , представляющий полученного пользователя.

Возвращаемый тип

UserProxy

Исключения

CosmosHttpResponseError

Не удалось создать контейнер.

list_containers

Вывод списка контейнеров в базе данных.

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

Параметры

max_item_count
Обязательно

Максимальное количество элементов, возвращаемых в операции перечисления.

session_token
str

Маркер для использования с согласованностью сеанса.

initial_headers
dict[str,str]

Начальные заголовки, отправляемые в составе запроса.

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

Возвращаемое значение

Итератор свойств контейнера (диктов).

Возвращаемый тип

Iterable[dict[str, Any]]

Исключения

CosmosHttpResponseError

Не удалось создать контейнер.

Примеры

Список всех контейнеров в базе данных:


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

list_users

Вывод списка всех пользователей в контейнере.

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

Параметры

max_item_count
Обязательно

Максимальное число пользователей, возвращаемых в операции перечисления.

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

Возвращаемое значение

Итерируемый объект свойств пользователя (диктов).

Возвращаемый тип

Iterable[dict[str, Any]]

Исключения

CosmosHttpResponseError

Не удалось создать контейнер.

query_containers

Список свойств контейнеров в текущей базе данных.

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

Параметры

query
Обязательно

Выполняемый SQL-запрос Azure Cosmos DB.

parameters
Обязательно

Необязательный массив параметров для запроса. Игнорируется, если запрос не предоставлен.

max_item_count
Обязательно

Максимальное количество элементов, возвращаемых в операции перечисления.

session_token
str

Маркер для использования с согласованностью сеанса.

initial_headers
dict[str,str]

Начальные заголовки, отправляемые в составе запроса.

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

Возвращаемое значение

Итератор свойств контейнера (диктов).

Возвращаемый тип

Iterable[dict[str, Any]]

Исключения

CosmosHttpResponseError

Не удалось создать контейнер.

query_users

Возвращает всех пользователей, соответствующих заданному запросу.

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

Параметры

query
Обязательно

Выполняемый SQL-запрос Azure Cosmos DB.

parameters
Обязательно

Необязательный массив параметров для запроса. Игнорируется, если запрос не предоставлен.

max_item_count
Обязательно

Максимальное число пользователей, возвращаемых в операции перечисления.

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

Возвращаемое значение

Итерируемый объект свойств пользователя (диктов).

Возвращаемый тип

Iterable[str, Any]

Исключения

CosmosHttpResponseError

Не удалось создать контейнер.

read

Чтение свойств базы данных.

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

Параметры

session_token
str

Маркер для использования с согласованностью сеанса.

initial_headers
dict[str,str]

Начальные заголовки, отправляемые в составе запроса.

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

Возвращаемый тип

Dict[<xref:Str>, Any]

Исключения

CosmosHttpResponseError

Значение , если не удалось получить указанную базу данных.

read_offer

Получите объект ThroughputProperties для этой базы данных. Если свойства ThroughputProperties для базы данных еще не существуют, возникает исключение. :ключевое слово Вызываемый response_hook: вызываемый объект с метаданными ответа. :returns: ThroughputProperties для базы данных. :raises ~azure.cosmos.exceptions.CosmosHttpResponseError: свойства пропускной способности для контейнера или

Не удалось получить свойства пропускной способности.

read_offer(**kwargs: Any) -> ThroughputProperties

Возвращаемый тип

ThroughputProperties

Исключения

CosmosHttpResponseError

Не удалось создать контейнер.

replace_container

Сбросьте свойства контейнера.

Изменения свойств сохраняются немедленно. Все не указанные свойства будут сброшены до значений по умолчанию.

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

Параметры

container
Обязательно

Идентификатор (имя), представляющий свойства или <xref:azure.cosmos.database.ContainerProxy> экземпляр заменяемого контейнера.

partition_key
Обязательно

Ключ секции, используемый для контейнера.

indexing_policy
Обязательно

Политика индексирования, применяемая к контейнеру.

default_ttl
Обязательно

Срок жизни (TTL) по умолчанию для элементов в контейнере. Если это не указано, срок действия элементов не истекает.

conflict_resolution_policy
Обязательно

Политика разрешения конфликтов, применяемая к контейнеру.

populate_query_metrics
Обязательно

Включите возвращаемые метрики запросов в заголовках ответов.

session_token
str

Маркер для использования с согласованностью сеанса.

etag
str

Значение ETag или подстановочный знак (*). Используется для проверка, если ресурс изменился, и действует в соответствии с условием, заданным параметром match_condition.

match_condition
MatchConditions

Условие соответствия, используемое для etag.

initial_headers
dict[str,str]

Начальные заголовки, отправляемые в составе запроса.

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

analytical_storage_ttl
int

Срок жизни аналитического хранилища (TTL) для элементов в контейнере. Значение None оставляет аналитическое хранилище отключенным, а значение -1 включает аналитическое хранилище без срока жизни. Обратите внимание, что аналитическое хранилище можно включить только в учетных записях с поддержкой Synapse Link.

Возвращаемое значение

Экземпляр ContainerProxy , представляющий контейнер после завершения замены.

Возвращаемый тип

ContainerProxy

Исключения

CosmosHttpResponseError

Возникает, если не удается заменить контейнер. Сюда входит значение , если контейнер с заданным идентификатором не существует.

Примеры

Сбросьте свойство TTL контейнера и отобразите обновленные свойства:


   # 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

Замените пропускную способность на уровне базы данных.

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

Параметры

throughput
Обязательно

Задается пропускная способность (целое число).

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

Возвращаемое значение

ThroughputProperties для базы данных, обновлена новая пропускная способность.

Возвращаемый тип

ThroughputProperties

Исключения

CosmosHttpResponseError

Значение , если для базы данных не существует свойств пропускной способности или не удалось обновить свойства пропускной способности.

replace_user

Заменяет указанного пользователя, если он существует в контейнере.

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

Параметры

user
Обязательно

Идентификатор (имя), дикт, представляющий свойства или <xref:azure.cosmos.database.UserProxy> экземпляр пользователя, который требуется заменить.

body
Обязательно

Объект, похожий на диктовку, представляющий пользователя, который требуется заменить.

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

Возвращаемое значение

Экземпляр UserProxy , представляющий пользователя после выполнения замены.

Возвращаемый тип

UserProxy

Исключения

CosmosHttpResponseError

Если не удалось выполнить замену или пользователь с указанным идентификатором не существует.

upsert_user

Вставьте или обновите указанного пользователя.

Если пользователь уже существует в контейнере, он заменяется. Если пользователь еще не существует, он вставляется.

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

Параметры

body
Обязательно

Объект, похожий на диктовку, представляющий пользователя для обновления или вставки.

response_hook
Callable

Вызываемый объект , вызываемый с метаданными ответа.

Возвращаемое значение

Экземпляр UserProxy , представляющий пользователя с upserted.

Возвращаемый тип

UserProxy

Исключения

CosmosHttpResponseError

Значение , если не удалось выполнить upsert данного пользователя.