CosmosClient Класс

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

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

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

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

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

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

builtins.object

CosmosClient

Конструктор

CosmosClient(url: str, credential: Any, consistency_level: str | None = None, **kwargs: Any)

Параметры

url

str

Обязательно

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

credential

Union[str, Dict[str, str], TokenCredential]

Обязательно

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

consistency_level

str

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

Уровень согласованности, используемый для сеанса. Значение по умолчанию — 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:

   from azure.cosmos import exceptions, CosmosClient, PartitionKey

   import os

   url = os.environ["ACCOUNT_URI"]
   key = os.environ["ACCOUNT_KEY"]
   client = CosmosClient(url, key)

Методы

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

create_database

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

create_database(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

Параметры

id

Обязательно

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

offer_throughput

Обязательно

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

session_token

str

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

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

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

response_hook

Callable

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

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

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

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

DatabaseProxy

Исключения

CosmosResourceExistsError

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

Примеры

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

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

create_database_if_not_exists

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

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

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

create_database_if_not_exists(id: str, populate_query_metrics: bool | None = None, offer_throughput: int | ThroughputProperties | None = None, **kwargs: Any) -> DatabaseProxy

Параметры

id

Обязательно

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

populate_query_metrics

bool

Обязательно

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

offer_throughput

int или <xref:azure.cosmos.ThroughputProperties.>

Обязательно

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

session_token

str

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

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

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

response_hook

Callable

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

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

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

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

DatabaseProxy

Исключения

CosmosHttpResponseError

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

delete_database

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

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

Параметры

database

str или dict(str, str) или DatabaseProxy

Обязательно

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

session_token

str

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

initial_headers

dict[str,str]

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

etag

str

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

match_condition

MatchConditions

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

response_hook

Callable

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

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

None

Исключения

CosmosHttpResponseError

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

from_connection_string

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

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

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

Параметры

conn_str

str

Обязательно

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

credential

str или dict(str, str)

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

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

consistency_level

Optional[str]

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

Уровень согласованности, используемый для сеанса. Значение по умолчанию — None (уровень учетной записи).

Исключения

CosmosResourceExistsError

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

get_database_account

Получение сведений об учетной записи базы данных.

get_database_account(**kwargs: Any) -> DatabaseAccount

Параметры

response_hook

Callable

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

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

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

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

DatabaseAccount

Исключения

CosmosResourceExistsError

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

get_database_client

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

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

Параметры

database

str или dict(str, str) или DatabaseProxy

Обязательно

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

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

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

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

DatabaseProxy

Исключения

CosmosResourceExistsError

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

list_databases

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

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

Параметры

max_item_count

int

Обязательно

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

session_token

str

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

initial_headers

dict[str,str]

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

response_hook

Callable

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

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

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

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

Iterable[dict[str, str]]

Исключения

CosmosResourceExistsError

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

query_databases

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

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

Параметры

query

str

Обязательно

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

parameters

List[Dict[str, Any]]

Обязательно

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

enable_cross_partition_query

bool

Обязательно

Разрешение сканирования запросов, которые не могли быть обработаны в качестве индексирования, было отказано в запрошенных путях.

max_item_count

int

Обязательно

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

session_token

str

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

initial_headers

dict[str,str]

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

response_hook

Callable

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

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

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

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

Iterable[dict[str, str]]

Исключения

CosmosResourceExistsError

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