dynamix-python-sdk/README.md

Dynamix Python SDK

• Описание
• Системные требования
  • Соответствие версий платформы версиям SDK
  • Зависимости
• Установка
• Использование
  • Конфигурация
  • Функциональный интерфейс
    • Вызов функции
    • Результат выполнения функции
    • Соответствие названий
  • Типы данных SDK
  • Ошибки и исключения (exceptions)
    • Ошибки валидации данных
    • Ошибки HTTP
• Доступный функционал
  • Способы авторизации
  • Функции API
    • Cloudapi
    • System

Описание

Dynamix Python SDK предоставляет удобный интерфейс для интеграции взаимодействия с API Dynamix Enterprise в программный код на языке Python.

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

Системные требования

Соответствие версий платформы версиям SDK

Версия платформы	Версия SDK
4.2.0	1.0.x

Зависимости

Зависимости указаны в конфигурационном файле проекта pyproject.toml:

• версия Python: раздел [project], ключ requires-python
• библиотеки: раздел [project], ключ dependencies

Важно: использование более поздних версий Python и/или библиотек допустимо, но работоспособность не гарантируется, так как зависит от обратной совместимости с указанными версиями.

Установка

Установка с помощью системы управления пакетами Python (pip), где version - тег с номером версии SDK (см. доступные теги в репозитории):

pip install git+https://repository.basistech.ru/BASIS/dynamix-python-sdk.git@version

Посмотреть версию установленного пакета:

pip show dynamix-sdk

Использование

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

Для работы с SDK необходимо создать экземпляр класса Dynamix, конструктор которого принимает на вход параметры конфигурации SDK.

Авторизация с JWT

from dynamix_sdk import Dynamix


JWT = '...'

dx = Dynamix(
    url='https://...',
    auth=JWT,
)

Авторизация через DECS3O

from dynamix_sdk import Dynamix, DECS3OAuth


dx = Dynamix(
    url='https://...',
    auth=DECS3OAuth(
        url='https://...',
        client_id='...',
        client_secret='...',
    ),
)

Авторизация через BVS

from dynamix_sdk import Dynamix, BVSAuth


dx = Dynamix(
    url='https://...',
    auth=BVSAuth(
        url='https://...',
        domain='...',
        client_id='...',
        client_secret='...',
        username='...',
        password='...',
    ),
)

Настройка повторных попыток при 503

По умолчанию SDK при получении кода ответа 503 производит 10 повторных попыток с интервалом 5 секунд. Данное поведение можно скорректировать:

from dynamix_sdk import Dynamix, DECS3OAuth, BVSAuth

# Для HTTP-запросов к Dynamix
Dynamix(
    ...,
    http503_attempts = 10,  # количество повторных попыток при 503
    http503_attempts_interval = 5,  # интервал в секундах между повторными попытками
)

# Для HTTP-запросов к DECS3O
DECS3OAuth(
    ...,
    http503_attempts = 10,  # количество повторных попыток при 503
    http503_attempts_interval = 5,  # интервал в секундах между повторными попытками
)

# Для HTTP-запросов к BVS
BVSAuth(
    ...,
    http503_attempts = 10,  # количество повторных попыток при 503
    http503_attempts_interval = 5,  # интервал в секундах между повторными попытками
)

Отключение проверки сертификата SSL

Важно: отключение проверки сертификата SSL даёт возможность произвести атаку типа MitM, поэтому пользоваться данной возможостью допустимо только в защищённой среде.

import urllib3

from dynamix_sdk import Dynamix, DECS3OAuth, BVSAuth


urllib3.disable_warnings()  # отключение вывода предупреждений безопасности SSL


# Для HTTP-запросов к Dynamix
Dynamix(
    ...,
    verify_ssl=False, # отключение проверки сертификата SSL
)

# Для HTTP-запросов к DECS3O
DECS3OAuth(
    ...,
    verify_ssl=False,  # отключение проверки сертификата SSL
)

# Для HTTP-запросов к BVS
BVSAuth(
    ...,
    verify_ssl=False,  # отключение проверки сертификата SSL
)

Функциональный интерфейс

Функциональный интерфейс предоставляет функции, соответствующие функциям API платформы.

Вызов функции

Выбор функции, передача параметров и сохранение результата

Передача вложенных параметров

from dynamix_sdk import Dynamix, types


dx = Dynamix(...)

data_disk_1 = types.DiskAPIParamsNM(name='data_disk_1', size=10)

# /cloudapi/kvmx86/create
new_vm_id = dx.api.cloudapi.kvmx86.create(
    rg_id=123,
    name='new_vm',
    cpu=1,
    ram=1024,
    image_id=456,
    data_disks=[data_disk_1],
)

Передача параметров перечисляемого типа (enum)

from dynamix_sdk import Dynamix, types


dx = Dynamix(...)

# /cloudapi/kvmx86/create
new_vm_id = dx.api.cloudapi.kvmx86.create(
    rg_id=123,
    name='new_vm',
    cpu=1,
    ram=1024,
    image_id=456,
    chipset=types.Chipset.Q35, # enum
    numa_affinity=types.NumaAffinity.none,  # enum
)

Результат выполнения функции

Тип данных, возвращаемый функцией API SDK зависит от типа данных, возвращаемого соответствующей функцией API платформы.

Если функция API платформы возвращает структуру данных в виде набора пар ключ/значение (с заранее известными ключами), то функция API SDK возвращает модель Pydantic, которая описывает эту структуру.

Модель

import pydantic
from dynamix_sdk import Dynamix


dx = Dynamix(...)

# /cloudapi/compute/get
get_result = dx.api.cloudapi.compute.get(compute_id=1)

print(type(get_result))  # <class '....CloudapiComputeGetResultModel'>

print(isinstance(get_result, pydantic.BaseModel))  # True

Обращение к полю модели

from dynamix_sdk import Dynamix


dx = Dynamix(...)

# /cloudapi/compute/get
vm_name = dx.api.cloudapi.compute.get(compute_id=1).name

Вложенные структуры данных также представлены в виде моделей Pydantic:

Вложенная модель

import pydantic
from dynamix_sdk import Dynamix


dx = Dynamix(...)

# /cloudapi/compute/get
vm_disk1 = dx.api.cloudapi.compute.get(compute_id=1).disks[0]

print(type(vm_disk1))  # <class '....DiskAPIResultNM'>

print(isinstance(vm_disk1, pydantic.BaseModel))  # True

Обращение к полю вложенной модели

from dynamix_sdk import Dynamix


dx = Dynamix(...)

# /cloudapi/compute/get
vm_disk1_id = dx.api.cloudapi.compute.get(compute_id=1).disks[0].id

Некоторые поля моделей автоматически генерируются на основе полученных данных от API платформы.
Например, при наличии в модели поля, содержащего временную метку (timestamp), для удобства генерируется поле, содержащее дату и время в виде datetime.

Генерируемое поле

from dynamix_sdk import Dynamix


dx = Dynamix(...)

# /cloudapi/compute/get
get_result = dx.api.cloudapi.compute.get(compute_id=1)

# Поле, возвращаемое платформой
print(type(get_result.created_timestamp))  # <class 'int'>

# Генерируемое поле
print(type(get_result.created_datetime))  # <class 'datetime.datetime'>

Если функция API платформы возвращает примитивный тип данных (строка, число), то функция API SDK возвращает экземпляр класса, наследуемый от класса этого типа данных.

Класс, наследуемый от примитивного типа данных

from dynamix_sdk import Dynamix


dx = Dynamix(...)

# /cloudapi/kvmx86/create
new_vm_id = dx.api.cloudapi.kvmx86.create(...)

print(type(new_vm_id))  # <class '....CloudapiKvmx86CreateResultInt'>

print(isinstance(new_vm_id, int))  # True

Исключением является булев тип данных. Так как наследование от класса bool в Python недопустимо, функция API SDK возвращает экземпляр класса, который обладает функциональностью для использования в булевых выражениях (реализован метод __bool__), но само булево значение хранится в атрибуте value:

Класс с булевым значением

from dynamix_sdk import Dynamix


dx = Dynamix(...)

# /cloudapi/compute/delete
delete_result = dx.api.cloudapi.compute.delete(compute_id=1)

print(type(delete_result))  # <class '....CloudapiComputeDeleteResultBool'>
print(type(delete_result.value))  # <class 'bool'>

Использование в булевом выражении:

from dynamix_sdk import Dynamix


dx = Dynamix(...)

# /cloudapi/compute/delete
if dx.api.cloudapi.compute.delete(compute_id=1):
    print('The VM has been deleted.')

Все объекты, возвращаемые функциями API SDK, обладают общими специальными атрибутами:

Атрибут	Описание
_api_params	Модель Pydantic, описывающая параметры, переданные в функцию.
_http_response	HTTP-ответ API платформы в виде экземпляра класса requests.Response.

Соответствие названий

В SDK названия из API платформы приведены к стилю "snake_case", принятому в Python, а в некоторых случаях имеют иные отличия, при этом сохраняя смысл исходного названия в API платформы.

Для соответствия названий в SDK используются таблицы соответствия, с помощью которых можно узнать исходное название в API платформы.
Каждая такая таблица хранится в виде словаря в файле YAML:

• api/path_mapping.yml - таблица соответствия названий частей маршрута (URL path) к функции API.
  Данная таблица содержит только те названия, которые отличаются от названий в API платформы.

• api/name_mapping.yml - таблица соответствия названий параметров функций и полей возвращаемых данных.
  Данная таблица содержит все названия, в том числе и те, которые совпадают с названиями в API платформы.
  Кроме общих соответствий, данная таблица также содержит индивидуальные соответствия, которые применяются только к классу модели, указанному в формате sdk_name__model_class_name.

Типы данных SDK

Все типы данных (классы) SDK, которые могут пригодиться при разработке ПО с использованием SDK, доступны через модуль dynamix_sdk.types.

Ошибки и исключения (exceptions)

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

Ошибки валидации данных

SDK производит валидацию параметров функций API с помощью библиотеки Pydantic.
Поэтому, при ошибке валидации, будет вызвано исключение pydantic.ValidationError.

Таким же образом валидируются данные HTTP-ответов API платформы. Причиной ошибки валидации данных HTTP-ответа API платформы может быть:

1. Несоответствие версии SDK и версии платформы.
2. Программная ошибка, допущенная при разработке SDK или платформы. Получить подтверждение наличия такой ошибки, а также ускорить её устранение, можно сообщив о ней.

Получить подробную информацию об исключении pydantic.ValidationError можно в соответствующем разделе официальной документации Pydantic (ссылка ведёт на документацию для последней версии, поэтому важно выбрать версию, соответствующую используемой в SDK).

Ошибки HTTP

SDK для выполнения HTTP-запросов использует библиотеку Requests.
Поэтому, при ошибке HTTP-подключения, будет вызвано соответствующее исключение библиотеки Requests.

Для проверки соответствует ли код ответа успешному выполнению запроса, SDK вызывает метод requests.Response.raise_for_status(), поэтому при неуспешном HTTP-запросе также будет вызвано исключение библиотеки Requests.

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

Обработка ошибок HTTP

from requests.exceptions import RequestException, HTTPError
from dynamix_sdk import Dynamix


dx = Dynamix(...)

vm_id = 1

try:
    get_result = dx.api.cloudapi.compute.get(compute_id=vm_id)
except HTTPError as e:
    resp = e.response
    if resp.status_code == 404:
        print(f'The VM ID={vm_id} not found.')
    else:
        print(f'{e}: {resp.text}')
except RequestException as e:
    print(e)

Подробную информацию об исключениях библиотеки Requests можно получить в соответствующем разделе официальной документации Requests.

Доступный функционал

Способы авторизации

• с JWT
• через DECS3O
• через BVS

Подробнее в разделе Конфигурация.

Функции API

Cloudapi

account

• /cloudapi/account/addUser
• /cloudapi/account/deleteUser
• /cloudapi/account/disable
• /cloudapi/account/enable
• /cloudapi/account/updateUser

compute

• /cloudapi/compute/delete
• /cloudapi/compute/get
• /cloudapi/compute/list
• /cloudapi/compute/update

kvmx86

• /cloudapi/kvmx86/create

rg

• /cloudapi/rg/create
• /cloudapi/rg/get
• /cloudapi/rg/list

user

• /cloudapi/user/get

System

usermanager

• /system/usermanager/whoami