CosmosClient Класс

Логическое представление учетной записи Azure Cosmos DB на стороне клиента.

Этот клиент используется для настройки и выполнения запросов к службе Azure Cosmos DB.

Рекомендуется поддерживать один экземпляр CosmosClient на время существования приложения, что обеспечивает эффективное управление подключениями и производительность.

Инициализация CosmosClient — это тяжелая операция. Не используйте инициализацию экземпляров CosmosClient в качестве учетных данных или проверки сетевого подключения.

Создайте экземпляр нового CosmosClient.

Наследование

builtins.object

CosmosClient

Конструктор

CosmosClient(url: str, credential: str | Dict[str, str] | TokenCredential, *, consistency_level: str | None = None, **kwargs: Any)

Параметры

url

str

Обязательно

URL-адрес учетной записи Cosmos DB.

credential

Union[str, Dict[str, str], AsyncTokenCredential]

Обязательно

Может быть ключом учетной записи или словарем маркеров ресурсов.

consistency_level

str

Уровень согласованности, используемый для сеанса. Значение по умолчанию — None (уровень учетной записи). Дополнительные сведения об уровнях согласованности и возможных значениях: https://aka.ms/cosmos-consistency-levels

timeout

int

Абсолютное время ожидания в секундах для объединенной обработки HTTP-запроса и ответа.

connection_timeout

int

Время ожидания HTTP-запроса в секундах.

connection_mode

str

Режим подключения для клиента в настоящее время поддерживает только "Шлюз".

proxy_config

ProxyConfiguration

Конфигурация прокси-сервера подключения.

ssl_config

SSLConfiguration

Конфигурация SSL подключения.

connection_verify

bool

Проверяется ли подключение, значение по умолчанию — True.

connection_cert

str

Альтернативный сертификат для проверки подключения.

retry_total

int

Максимальное число повторных попыток.

retry_backoff_max

int

Максимальное время ожидания повторных попыток в секундах.

retry_fixed_interval

int

Фиксированный интервал повторных попыток в миллисекундах.

retry_read

int

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

retry_connect

int

Максимальное число повторных попыток ошибки подключения.

retry_status

int

Максимальное число повторных попыток с кодами состояния ошибок.

retry_on_status_codes

list[int]

Список конкретных кодов состояния для повторных попыток.

retry_backoff_factor

float

Фактор для вычисления времени ожидания между повторными попытками.

enable_endpoint_discovery

bool

Включите обнаружение конечных точек для учетных записей геореплицированных баз данных. (Значение по умолчанию — True.)

preferred_locations

list[str]

Предпочтительные расположения для учетных записей геореплицированных баз данных.

enable_diagnostics_logging

bool

Включите политику CosmosHttpLogging. Для работы необходимо использовать вместе со средствами ведения журнала.

logger

Logger

Средство ведения журнала, используемое для сбора диагностика запросов. Может передаваться на уровне клиента (для регистрации всех запросов) или на уровне одного запроса. Запросы будут регистрироваться на уровне INFO.

Примеры

Создайте новый экземпляр клиента Cosmos DB:

       async with CosmosClient(url, key) as client:

Методы

close	Закройте этот экземпляр CosmosClient.
create_database	Создайте базу данных с заданным идентификатором (именем).
create_database_if_not_exists	Создайте базу данных, если она еще не существует. Если база данных уже существует, возвращаются существующие параметры. .. Примечание. Эта функция не проверка или не обновляет существующие параметры базы данных или не предлагает пропускную способность, если они отличаются от передаваемых.
delete_database	Удалите базу данных с указанным идентификатором (именем).
from_connection_string	Создайте экземпляр CosmosClient из строки подключения. Его можно получить из портал Azure. Полный список необязательных аргументов ключевое слово см. в конструкторе CosmosClient.
get_database_client	Получение существующей базы данных с идентификатором (именем).
list_databases	Вывод списка баз данных в учетной записи базы данных SQL Cosmos DB.
query_databases	Запрос баз данных в учетной записи базы данных SQL Cosmos DB.

close

Закройте этот экземпляр CosmosClient.

async close() -> None

create_database

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

async create_database(id: str, **kwargs: Any) -> DatabaseProxy

Параметры

id

str

Обязательно

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

offer_throughput

Union[int, ThroughputProperties]

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

session_token

str

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

initial_headers

dict[str, str]

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

etag

str

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

match_condition

MatchConditions

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

response_hook

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

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

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

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

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

DatabaseProxy

Исключения

CosmosResourceExistsError

База данных с указанным идентификатором уже существует.

Примеры

Создайте базу данных в учетной записи Cosmos DB:

           database_name = "testDatabase"
           try:
               database = await client.create_database(id=database_name)
           except exceptions.CosmosResourceExistsError:
               database = client.get_database_client(database=database_name)

create_database_if_not_exists

Создайте базу данных, если она еще не существует.

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

.. Примечание. Эта функция не проверка или не обновляет существующие параметры базы данных или не предлагает пропускную способность, если они отличаются от передаваемых.

async create_database_if_not_exists(id: str, **kwargs: Any) -> DatabaseProxy

Параметры

id

str

Обязательно

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

offer_throughput

Union[int, ThroughputProperties]

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

session_token

str

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

initial_headers

dict[str, str]

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

etag

str

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

match_condition

MatchConditions

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

response_hook

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

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

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

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

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

DatabaseProxy

Исключения

CosmosHttpResponseError

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

delete_database

Удалите базу данных с указанным идентификатором (именем).

async delete_database(database: str | DatabaseProxy | Dict[str, Any], **kwargs: Any) -> None

Параметры

database

Union[str, DatabaseProxy, Dict[str, Any]]

Обязательно

Идентификатор (имя), дикт, представляющий свойства, или DatabaseProxy экземпляр удаляемой базы данных.

session_token

str

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

initial_headers

dict[str, str]

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

etag

str

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

match_condition

MatchConditions

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

response_hook

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

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

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

None

Исключения

CosmosHttpResponseError

Если не удалось удалить базу данных.

from_connection_string

Создайте экземпляр CosmosClient из строки подключения.

Его можно получить из портал Azure. Полный список необязательных аргументов ключевое слово см. в конструкторе CosmosClient.

from_connection_string(conn_str: str, *, credential: str | Dict[str, str] | None = None, consistency_level: str | None = None, **kwargs: Any) -> CosmosClient

Параметры

conn_str

str

Обязательно

Строка подключения.

credential

Union[str, Dict[str, str]]

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

consistency_level

str

Уровень согласованности, используемый для сеанса. Значение по умолчанию — None (уровень учетной записи). Дополнительные сведения об уровнях согласованности и возможных значениях: https://aka.ms/cosmos-consistency-levels

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

экземпляр CosmosClient

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

CosmosClient

get_database_client

Получение существующей базы данных с идентификатором (именем).

get_database_client(database: str | DatabaseProxy | Dict[str, Any]) -> DatabaseProxy

Параметры

database

Union[str, DatabaseProxy, Dict[str, Any]]

Обязательно

Идентификатор (имя), дикт, представляющий свойства, или DatabaseProxy экземпляр базы данных, которую требуется получить.

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

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

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

DatabaseProxy

list_databases

Вывод списка баз данных в учетной записи базы данных SQL Cosmos DB.

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

Параметры

max_item_count

int

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

session_token

str

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

initial_headers

dict[str, str]

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

response_hook

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

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

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

AsyncItemPaged свойств базы данных (dicts).

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

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

query_databases

Запрос баз данных в учетной записи базы данных SQL Cosmos DB.

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

Параметры

query

Union[str, Dict[str, Any]]

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

parameters

List[Dict[str, Any]]

Необязательный массив параметров для запроса. Каждый параметр представляет собой dict() с ключами name и value.

max_item_count

int

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

session_token

str

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

initial_headers

dict[str, str]

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

response_hook

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

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

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

AsyncItemPaged свойств базы данных (dicts).

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

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