34 KiB

Raw Blame History Unescape Escape

Dynamix Python SDK

Описание
Системные требования
- Соответствие версий платформы версиям SDK
- Зависимости
Установка
Использование
Доступный функционал
- Способы авторизации
- Функции API

Описание

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

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

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

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

Версия платформы	Версия SDK
4.4.0	1.3.x
4.4.0 build 963	1.2.x
4.3.0	1.1.x
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='...',
    ),
)

Задание декораторов для всех вызываемых функций

from dynamix_sdk import Dynamix


Dynamix(
    ...,
    f_decorators=[decorator_1, decorator_2],
)

Декораторы будут применяться к вызываемым функциям SDK в обратном порядке, то есть сначала будет применяться декоратор decorator_2, а потом decorator_1.

Важно: декораторы должны соответствовать аннотации параметра, то есть оставлять без изменений параметры и тип возвращаемого значения функции, иначе применение декораторов приведёт к некорректной работе SDK.

Настройка повторных попыток при 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

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

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

from dynamix_sdk import Dynamix


Dynamix(
    ...,
    ignore_api_compatibility=True,
)

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

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

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

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

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

from dynamix_sdk import Dynamix, types


dx = Dynamix(...)

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

# /cloudapi/kvmx86/create
new_vm_id = dx.api.cloudapi.kvmx86.create(
    rg_id=123,
    name='new_vm',
    cpu_count=1,
    ram_size_mb=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_count=1,
    ram_size_mb=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(vm_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(vm_id=1).name

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

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

import pydantic
from dynamix_sdk import Dynamix


dx = Dynamix(...)

# /cloudapi/compute/get
vm_disk1 = dx.api.cloudapi.compute.get(vm_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(vm_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(vm_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(vm_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(vm_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 платформы может быть:

Несоответствие версии SDK и версии платформы.
Программная ошибка, допущенная при разработке 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(vm_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.

Использование исключения SDK

Для возможности получать дополнительную информацию о функциях SDK при ошибках HTTP-запросов, в SDK есть возможность оборачивать все исключения requests.exceptions.RequestException в исключение dynamix_sdk.exceptions.RequestException:

class RequestException(Exception):
    orig_exception: requests.exceptions.RequestException
    func_name: str
    func_kwargs: None | dict = None

Чтобы включить использование исключения dynamix_sdk.exceptions.RequestException, необходимо передать в конструкторы классов Dynamix, DECS3OAuth, BVSAuth параметр wrap_request_exceptions=True

Ошибка несовместимости с API

SDK производит проверку совместимости с API. При несовместимости будет вызвано исключение exceptions.IncompatibleAPIError.

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

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

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

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

Функции API

Cloudapi

account

/cloudapi/account/addUser
/cloudapi/account/delete
/cloudapi/account/deleteUser
/cloudapi/account/disable
/cloudapi/account/enable
/cloudapi/account/get
/cloudapi/account/getResourceConsumption
/cloudapi/account/list
/cloudapi/account/listDeleted
/cloudapi/account/restore
/cloudapi/account/update
/cloudapi/account/updateUser

audit

/cloudapi/audit/get
/cloudapi/audit/list

bservice

/cloudapi/bservice/create
/cloudapi/bservice/delete
/cloudapi/bservice/disable
/cloudapi/bservice/enable
/cloudapi/bservice/get
/cloudapi/bservice/groupAdd
/cloudapi/bservice/groupComputeRemove
/cloudapi/bservice/groupGet
/cloudapi/bservice/groupParentAdd
/cloudapi/bservice/groupParentRemove
/cloudapi/bservice/groupRemove
/cloudapi/bservice/groupResize
/cloudapi/bservice/groupStart
/cloudapi/bservice/groupStop
/cloudapi/bservice/groupUpdate
/cloudapi/bservice/groupUpdateExtnet
/cloudapi/bservice/groupUpdateVins
/cloudapi/bservice/list
/cloudapi/bservice/listDeleted
/cloudapi/bservice/migrateToZone
/cloudapi/bservice/restore
/cloudapi/bservice/snapshotCreate
/cloudapi/bservice/snapshotDelete
/cloudapi/bservice/snapshotList
/cloudapi/bservice/snapshotRollback
/cloudapi/bservice/start
/cloudapi/bservice/stop

compute

/cloudapi/compute/abort_shared_snapshot_merge
/cloudapi/compute/affinityLabelRemove
/cloudapi/compute/affinityLabelSet
/cloudapi/compute/affinityRelations
/cloudapi/compute/affinityRuleAdd
/cloudapi/compute/affinityRuleRemove
/cloudapi/compute/affinityRulesClear
/cloudapi/compute/antiAffinityRuleAdd
/cloudapi/compute/antiAffinityRuleRemove
/cloudapi/compute/antiAffinityRulesClear
/cloudapi/compute/attachGpu
/cloudapi/compute/attachPciDevice
/cloudapi/compute/bootDiskSet
/cloudapi/compute/cdEject
/cloudapi/compute/cdInsert
/cloudapi/compute/changeMac
/cloudapi/compute/change_mtu
/cloudapi/compute/change_security_groups
/cloudapi/compute/changeIp
/cloudapi/compute/changeLinkState
/cloudapi/compute/clone
/cloudapi/compute/clone_abort
/cloudapi/compute/createTemplate
/cloudapi/compute/delete
/cloudapi/compute/deleteCustomFields
/cloudapi/compute/detachGpu
/cloudapi/compute/detachPciDevice
/cloudapi/compute/disable
/cloudapi/compute/diskAdd
/cloudapi/compute/diskAttach
/cloudapi/compute/diskDel
/cloudapi/compute/diskDetach
/cloudapi/compute/diskMigrate
/cloudapi/compute/diskSwitchToReplication
/cloudapi/compute/enable
/cloudapi/compute/get
/cloudapi/compute/getConsoleUrl
/cloudapi/compute/guest_agent_disable
/cloudapi/compute/guest_agent_enable
/cloudapi/compute/guest_agent_execute
/cloudapi/compute/guest_agent_feature_update
/cloudapi/compute/list
/cloudapi/compute/listDeleted
/cloudapi/compute/migrateToZone
/cloudapi/compute/moveToRg
/cloudapi/compute/netAttach
/cloudapi/compute/netDetach
/cloudapi/compute/pause
/cloudapi/compute/pfwAdd
/cloudapi/compute/pfwDel
/cloudapi/compute/pfwList
/cloudapi/compute/pinToStack
/cloudapi/compute/powerCycle
/cloudapi/compute/reboot
/cloudapi/compute/redeploy
/cloudapi/compute/reset
/cloudapi/compute/resize
/cloudapi/compute/restore
/cloudapi/compute/resume
/cloudapi/compute/setCustomFields
/cloudapi/compute/snapshotCreate
/cloudapi/compute/snapshotList
/cloudapi/compute/snapshotRollback
/cloudapi/compute/start
/cloudapi/compute/stop
/cloudapi/compute/tagAdd
/cloudapi/compute/tagRemove
/cloudapi/compute/unpinFromStack
/cloudapi/compute/update
/cloudapi/compute/userGrant
/cloudapi/compute/userList
/cloudapi/compute/userRevoke
/cloudapi/compute/userUpdate

disks

/cloudapi/disks/change_disk_storage_policy
/cloudapi/disks/create
/cloudapi/disks/delete
/cloudapi/disks/deleteDisks
/cloudapi/disks/get
/cloudapi/disks/limitIO
/cloudapi/disks/list
/cloudapi/disks/listDeleted
/cloudapi/disks/listTypes
/cloudapi/disks/listUnattached
/cloudapi/disks/rename
/cloudapi/disks/resize2
/cloudapi/disks/restore
/cloudapi/disks/share
/cloudapi/disks/snapshotDelete
/cloudapi/disks/snapshotRollback
/cloudapi/disks/unshare

dpdknet

/cloudapi/dpdknet/get
/cloudapi/dpdknet/list

extnet

/cloudapi/extnet/get
/cloudapi/extnet/getDefault
/cloudapi/extnet/list

flipgroup

/cloudapi/flipgroup/computeAdd
/cloudapi/flipgroup/computeRemove
/cloudapi/flipgroup/create
/cloudapi/flipgroup/delete
/cloudapi/flipgroup/edit
/cloudapi/flipgroup/get
/cloudapi/flipgroup/list

image

/cloudapi/image/change_storage_policy
/cloudapi/image/create
/cloudapi/image/createVirtual
/cloudapi/image/delete
/cloudapi/image/get
/cloudapi/image/link
/cloudapi/image/list
/cloudapi/image/rename

k8ci

/cloudapi/k8ci/get
/cloudapi/k8ci/list
/cloudapi/k8ci/listDeleted

k8s

/cloudapi/k8s/create
/cloudapi/k8s/delete
/cloudapi/k8s/deleteMasterFromGroup
/cloudapi/k8s/deleteWorkerFromGroup
/cloudapi/k8s/disable
/cloudapi/k8s/enable
/cloudapi/k8s/get
/cloudapi/k8s/getConfig
/cloudapi/k8s/getNodeAnnotations
/cloudapi/k8s/getNodeLabels
/cloudapi/k8s/getNodeTaints
/cloudapi/k8s/list
/cloudapi/k8s/listDeleted
/cloudapi/k8s/migrateToZone
/cloudapi/k8s/restore
/cloudapi/k8s/start
/cloudapi/k8s/stop
/cloudapi/k8s/update
/cloudapi/k8s/updateWorkerNodesMetaData
/cloudapi/k8s/workerAdd
/cloudapi/k8s/workerReset
/cloudapi/k8s/workerRestart
/cloudapi/k8s/workersGroupAdd
/cloudapi/k8s/workersGroupDelete
/cloudapi/k8s/workersGroupGetByName

kvmx86

/cloudapi/kvmx86/create
/cloudapi/kvmx86/createBlank

/cloudapi/lb/backendCreate
/cloudapi/lb/backendDelete
/cloudapi/lb/backendServerAdd
/cloudapi/lb/backendServerDelete
/cloudapi/lb/backendServerUpdate
/cloudapi/lb/backendUpdate
/cloudapi/lb/configReset
/cloudapi/lb/create
/cloudapi/lb/delete
/cloudapi/lb/disable
/cloudapi/lb/enable
/cloudapi/lb/frontendBind
/cloudapi/lb/frontendBindDelete
/cloudapi/lb/frontendBindingUpdate
/cloudapi/lb/frontendCreate
/cloudapi/lb/frontendDelete
/cloudapi/lb/get
/cloudapi/lb/list
/cloudapi/lb/listDeleted
/cloudapi/lb/makeHighlyAvailable
/cloudapi/lb/migrateToZone
/cloudapi/lb/restart
/cloudapi/lb/restore
/cloudapi/lb/start
/cloudapi/lb/stop
/cloudapi/lb/update
/cloudapi/lb/updateSysctlParams

locations

/cloudapi/locations/getUrl
/cloudapi/locations/list

pcidevice

/cloudapi/pcidevice/list

/cloudapi/rg/accessGrant
/cloudapi/rg/accessRevoke
/cloudapi/rg/add_storage_policy
/cloudapi/rg/create
/cloudapi/rg/del_storage_policy
/cloudapi/rg/delete
/cloudapi/rg/disable
/cloudapi/rg/enable
/cloudapi/rg/get
/cloudapi/rg/getResourceConsumption
/cloudapi/rg/list
/cloudapi/rg/listDeleted
/cloudapi/rg/removeDefNet
/cloudapi/rg/restore
/cloudapi/rg/setDefNet
/cloudapi/rg/update

security_group

/cloudapi/security_group/get
/cloudapi/security_group/create
/cloudapi/security_group/create_rule
/cloudapi/security_group/delete
/cloudapi/security_group/delete_rule
/cloudapi/security_group/list
/cloudapi/security_group/update

sep

/cloudapi/sep/listAvailableSepAndPools

stack

/cloudapi/stack/get
/cloudapi/stack/list

storage_policy

/cloudapi/storage_policy/get
/cloudapi/storage_policy/list

tasks

/cloudapi/tasks/get
/cloudapi/tasks/list

trunk

/cloudapi/trunk/get
/cloudapi/trunk/list

user

/cloudapi/user/apiList
/cloudapi/user/brief
/cloudapi/user/get
/cloudapi/user/getResourceConsumption
/cloudapi/user/setData

vfpool

/cloudapi/vfpool/get
/cloudapi/vfpool/list

vgpu

/cloudapi/vgpu/list

vins

/cloudapi/vins/createInAccount
/cloudapi/vins/createInRG
/cloudapi/vins/delete
/cloudapi/vins/disable
/cloudapi/vins/dnsApply
/cloudapi/vins/enable
/cloudapi/vins/extNetConnect
/cloudapi/vins/extNetDisconnect
/cloudapi/vins/extNetList
/cloudapi/vins/get
/cloudapi/vins/ipList
/cloudapi/vins/ipRelease
/cloudapi/vins/ipReserve
/cloudapi/vins/list
/cloudapi/vins/listDeleted
/cloudapi/vins/migrateToZone
/cloudapi/vins/natRuleAdd
/cloudapi/vins/natRuleDel
/cloudapi/vins/natRuleList
/cloudapi/vins/restore
/cloudapi/vins/staticRouteAdd
/cloudapi/vins/staticRouteDel
/cloudapi/vins/staticRouteList
/cloudapi/vins/vnfdevRedeploy
/cloudapi/vins/vnfdevRestart

zone

/cloudapi/zone/get
/cloudapi/zone/list

Cloudbroker