Поделиться через

Общая клиентская библиотека Azure Core для Python версии 1.29.6

  • Статья

Azure Core предоставляет общие исключения и модули для клиентских библиотек пакета SDK для Python. Эти библиотеки соответствуют рекомендациям по проектированию пакета Azure SDK для Python .

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

Исходный код | Пакет (Pypi) | Пакет (Conda) | Справочная документация по API

Заявление об отказе

Поддержка пакетов Python пакета Azure SDK для Python 2.7 завершилась 1 января 2022 г. Дополнительные сведения и вопросы см. на https://github.com/Azure/azure-sdk-for-python/issues/20691

Начало работы

Как правило, устанавливать Azure Core не требуется; он будет установлен при установке одной из клиентских библиотек с его помощью. Если вы хотите установить его явным образом (например, для реализации собственной клиентской библиотеки), его можно найти здесь.

Основные понятия

Исключения основной библиотеки Azure

AzureError

AzureError является базовым исключением для всех ошибок.

class AzureError(Exception):
    def __init__(self, message, *args, **kwargs):
        self.inner_exception = kwargs.get("error")
        self.exc_type, self.exc_value, self.exc_traceback = sys.exc_info()
        self.exc_type = self.exc_type.__name__ if self.exc_type else type(self.inner_exception)
        self.exc_msg = "{}, {}: {}".format(message, self.exc_type, self.exc_value)  # type: ignore
        self.message = str(message)
        self.continuation_token = kwargs.get("continuation_token")
        super(AzureError, self).__init__(self.message, *args)

message — это любое сообщение (str), связанное с исключением.

Аргументы — это любые дополнительные аргументы, которые должны быть включены с исключением.

kwargs — это ключевое слово аргументы для включения с исключением. Используйте ошибку ключевое слово для передачи внутреннего исключения и continuation_token ссылку на маркер, чтобы продолжить незавершенную операцию.

Следующие исключения наследуются от AzureError:

ServiceRequestError

При попытке выполнить запрос к службе произошла ошибка. Запрос не отправлен.

ServiceResponseError

Запрос был отправлен, но клиенту не удалось понять ответ. Возможно, истекло время ожидания подключения. Эти ошибки можно повторить для идемпотентных или безопасных операций.

HttpResponseError

Был сделан запрос, и от службы был получен код состояния, не выполненный.

class HttpResponseError(AzureError):
    def __init__(self, message=None, response=None, **kwargs):
        self.reason = None
        self.response = response
        if response:
            self.reason = response.reason
            self.status_code = response.status_code
        self.error = self._parse_odata_body(ODataV4Format, response)  # type: Optional[ODataV4Format]
        if self.error:
            message = str(self.error)
        else:
            message = message or "Operation returned an invalid status '{}'".format(
                self.reason
            )

        super(HttpResponseError, self).__init__(message=message, **kwargs)

message — это сообщение об ошибке HTTP-ответа (необязательно).

response — это HTTP-ответ (необязательно).

kwargs — это ключевое слово аргументы для включения с исключением.

Следующие исключения наследуются от HttpResponseError:

DecodeError

Ошибка, возникаемая во время десериализации ответа.

IncompleteReadError

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

ResourceExistsError

Ответ об ошибке с кодом состояния 4xx. Это не будет напрямую вызвано конвейером Azure Core.

ResourceNotFoundError

Ответ об ошибке, обычно активируется ответом 412 (для обновления) или 404 (для получения или публикации).

ResourceModifiedError

Ответ об ошибке с кодом состояния 4xx, как правило, конфликт 412. Это не будет напрямую вызвано конвейером Azure Core.

ResourceNotModifiedError

Ответ об ошибке с кодом состояния 304. Это не будет напрямую вызвано конвейером Azure Core.

ClientAuthenticationError

Ответ об ошибке с кодом состояния 4xx. Это не будет напрямую вызвано конвейером Azure Core.

TooManyRedirectsError

Ошибка, возникаемая при достижении максимального числа попыток перенаправления. Максимальное количество перенаправлений можно настроить в RedirectPolicy.

class TooManyRedirectsError(HttpResponseError):
    def __init__(self, history, *args, **kwargs):
        self.history = history
        message = "Reached maximum redirect attempts."
        super(TooManyRedirectsError, self).__init__(message, *args, **kwargs)

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

Аргументы — это любые дополнительные аргументы, которые должны быть включены с исключением.

kwargs — это ключевое слово аргументы для включения с исключением.

StreamConsumedError

При попытке получить доступ к потоку azure.core.rest.HttpResponse или azure.core.rest.AsyncHttpResponse после использования потока ответа возникает ошибка.

StreamClosedError

При попытке доступа к потоку azure.core.rest.HttpResponse или azure.core.rest.AsyncHttpResponse при закрытии потока ответа возникает ошибка.

ResponseNotReadError

При попытке contentazure.core.rest.HttpResponse получить доступ к или azure.core.rest.AsyncHttpResponse перед чтением в байтах ответа сначала возникает ошибка.

Конфигурации

При вызове методов некоторые свойства можно настроить, передав в качестве аргументов kwargs.

Параметры Описание
Заголовки Заголовки HTTP-запроса.
request_id Идентификатор запроса, добавляемого в заголовок.
user_agent Если этот параметр указан, он будет добавлен перед строкой агента пользователя.
logging_enable Используйте для включения каждой операции. По умолчанию — False.
logger Если он указан, он будет использоваться для записи в журнал данных.
response_encoding Кодировка, используемая, если она известна для этой службы (отключит автоматическое обнаружение).
прокси-серверы. Сопоставляет протокол или протокол и имя узла с URL-адресом прокси-сервера.
raw_request_hook Функция обратного вызова. Будет вызываться по запросу.
raw_response_hook Функция обратного вызова. Будет вызываться при ответе.
network_span_namer Вызываемый объект для настройки имени диапазона.
tracing_attributes Атрибуты, которые необходимо задать для всех созданных диапазонов.
permit_redirects Разрешает ли клиент перенаправления. По умолчанию — True.
redirect_max Максимально допустимые перенаправления. По умолчанию — 30.
retry_total Общее количество разрешенных повторных попыток. Имеет приоритет над другими счетчиками. Значение по умолчанию — 10.
retry_connect Сколько ошибок, связанных с подключением, необходимо повторить попытку. Это ошибки, возникающие перед отправкой запроса на удаленный сервер, который, как предполагается, не активировал сервер для обработки запроса. Значение по умолчанию — 3.
retry_read Количество повторных попыток при чтении ошибок. Эти ошибки возникают после отправки запроса на сервер, поэтому запрос может иметь побочные эффекты. Значение по умолчанию — 3.
retry_status Количество повторных попыток при неправильном коде состояния. Значение по умолчанию — 3.
retry_backoff_factor Коэффициент задержки, применяемый между попытками после второй попытки (большинство ошибок устраняются немедленно второй попыткой без задержки). Политика повтора будет в спящем режиме в течение: {backoff factor} * (2 ** ({number of total retries} - 1)) секунд. Если backoff_factor равно 0,1, то повторная попытка будет в спящем режиме [0.0s, 0.2s, 0.4s, ...] между повторными попытками. Значение по умолчанию — 0.8.
retry_backoff_max Максимальное время отката. Значение по умолчанию — секунды 120 (2 минуты).
retry_mode Фиксированная или экспоненциальная задержка между попытками. Значение по умолчанию — Exponential.
timeout Параметр времени ожидания для операции в секундах, по умолчанию — 604800s (7 дней).
connection_timeout Одно число с плавающей точкой в секундах для времени ожидания подключения. Значение по умолчанию — 300 секунды.
read_timeout Одно число с плавающей точкой в секундах для времени ожидания чтения. Значение по умолчанию — 300 секунды.
connection_verify Проверка SSL-сертификата. Включен по умолчанию. Установите значение False, чтобы отключить. Кроме того, можно задать путь к CA_BUNDLE файлу или каталогу с сертификатами доверенных ЦС.
connection_cert Сертификаты на стороне клиента. Вы можете указать локальный сертификат для использования в качестве сертификата на стороне клиента, как один файл (содержащий закрытый ключ и сертификат) или в качестве кортежа путей к обоим файлам.
прокси-серверы. Словарь сопоставляет протокол или протокол и имя узла с URL-адресом прокси-сервера.
файлы cookie Объект Dict или CookieJar для отправки Requestс помощью .
connection_data_block_size Размер блока данных, отправляемых через соединение. Значение по умолчанию — 4096 байты.

Асинхронный транспорт

Асинхронный транспорт предназначен для согласия. AioHttp — это одна из поддерживаемых реализаций асинхронного транспорта. По умолчанию он не установлен. Его необходимо установить отдельно.

Общие модули

MatchConditions

MatchConditions — это перечисление для описания условий соответствия.

class MatchConditions(Enum):
    Unconditionally = 1  # Matches any condition
    IfNotModified = 2  # If the target object is not modified. Usually it maps to etag=<specific etag>
    IfModified = 3  # Only if the target object is modified. Usually it maps to etag!=<specific etag>
    IfPresent = 4   # If the target object exists. Usually it maps to etag='*'
    IfMissing = 5   # If the target object does not exist. Usually it maps to etag!='*'

CaseInsensitiveEnumMeta

Метакласс для поддержки перечислений без учета регистра.

from enum import Enum

from azure.core import CaseInsensitiveEnumMeta

class MyCustomEnum(str, Enum, metaclass=CaseInsensitiveEnumMeta):
    FOO = 'foo'
    BAR = 'bar'

Значение Sentinel NULL

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

from azure.core.serialization import NULL

assert bool(NULL) is False

foo = Foo(
    attr=NULL
)

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения: Вопросы и ответы по правилам поведения. С любыми другими вопросами или комментариями обращайтесь по адресу opencode@microsoft.com.