Примеры использования API

В статье приведены упрощённые примеры на языке программирования python 3.6 с использованием библиотек json и request.

Проверка уровня доступа

Авторизуйтесь в VMmanager с правами администратора:

Аутентификация

url = "https://vm.example.com/auth/v4/public/token"
data = json.loads('{"email": "admin@example.com", "password": "123456"}')
auth = requests.post(url=url, json=data)

Получите информацию о пользователе:

Запрос информации о пользователе

token = json.loads(auth.content.decode('utf-8')).get('token')
url = "https://vm.example.com/auth/v4/whoami"
cookie = {'x-xsrf-token': f'{token}'}
whoami = requests.get(url=url, headers=cookie)

Проверьте наличие прав администратора у пользователя:
Проверка прав доступа
```
is_admin = '@admin' in json.loads(whoami.content.decode('utf-8')).get('roles')
```

Получение статуса задач

При создании длительной задачи в VMmanager в ответ приходит JSON-объект. Используйте его поле task, чтобы отфильтровать список всех задач:
Получение информации о задаче
```
url = f"https://vm.example.com/vm/v3/task?where=((consul_id+EQ+'{task_id}')+AND+(name+EQ+'{task_name}'))"
response = requests.get(url=url, headers=cookie)
task_info = json.loads(response.content.decode('utf-8')).get('list')[0]
```
Обработайте поле status в полученном JSON-объекте. Возможные значения:
- created — задача создана, но не запущена;
- running — задача запущена;
- deferred — запуск отложен;
- complete — задача выполнена;
- fail — задача завершилась с ошибкой.

Создание ВМ

Авторизуйтесь в VMmanager с правами администратора:

Авторизация

url = "https://vm.example.com/auth/v4/public/token"
data = json.loads('{"email": "admin@example.com", "password": "123456"}')
auth = requests.post(url=url, json=data)

Убедитесь, что пользователь зарегистрирован в VMmanager:

Поиск пользователя по email

email = "user@example.com"
url = f"https://vm.example.com/vm/v3/account?where=(email+EQ+'{email}')"
account_info = requests.get(url=url, headers=cookie)
user_registered = json.loads(account_info.content.decode('utf-8')).get('size') != 0

Если пользователь не найден, то зарегистрируйте его:

Добавление пользователя

data = json.loads('{"email": "user@example.com", "password": "strong_password", "role": "@user"}')
url = "https://vm.example.com/vm/v3/account"
new_user = requests.post(url=url, json=data, headers=cookie)

Сохраните ID пользователя. Он может быть получен из account_info (пункт 2) или после регистрации (пункт 3).
Сформируйте набор параметров ВМ:
- обязательные — имя, пароль root, ID кластера, ID аккаунта-владельца, список пулов IP-адресов;
- опциональный — доменное имя;
- ресурсы — количество процессоров, объём RAM, объём дискового пространства;
- ID образа операционной системы или ВМ.

Отправьте запрос на создание ВМ:

Создание ВМ

url = "https://vm.example.com/vm/v3/host"
new_host = requests.post(url=url, json=vm_params, headers=cookie)

Дождитесь завершения задачи.

Операции с ВМ

Удаление ВМ

url = f"https://vm.example.com/vm/v3/host/{host_id}"
deleted_host = requests.delete(url=url, headers=cookie)

Остановка ВМ

url = f"https://vm.example.com/vm/v3/host/{host_id}/stop"
data = json.loads('{}')
host = requests.post(url=url, json=data, headers=cookie)

Запуск ВМ

url = f"https://vm.example.com/vm/v3/host/{host_id}/start"
data = json.loads('{}')
host = requests.post(url=url, json=data, headers=cookie)

Операции с IP-адресами

Приведены примеры для IPv4.

Добавление IP-адреса

Получите список доступных пулов для кластера:

Получение IP-пулов кластера

url = f"https://vm.example.com/vm/v3/cluster?where=(id+EQ+'{cluster_id}')"
cluster_info = requests.get(url=url, headers=cookie)
cluster_ip_pools = json.loads(cluster_info.content.decode('utf-8')).get('list')[0].get('ippools')
ip_pools = [pool['id'] for pool in cluster_ip_pools]

Добавьте IP-адрес в один из полученных пулов:

Добавление адреса

url = f"https://vm.example.com/vm/v3/host/{host_id}/ip"
data = json.loads(f'{{"ipv4_number": {ipv4_number}, "ipv4_pool": {ip_pools}}}')
ip_add = requests.post(url=url, json=data, headers=cookie)

Добавление определённого IP-адреса

Добавление адреса

url = f"https://vm.example.com/vm/v3/host/{host_id}/ip"
data = {'ip_addr': {'name': ip_str, 'ip_pool': ip_pool_int, 'ip_network': ip_network_int}}
ip_add = requests.post(url=url, json=data, headers=cookie)

Удаление IP-адреса

Удаление адреса

url = f"https://vm.example.com/vm/v3/ip/{ip_id}"
ip_delete = requests.delete(url=url, headers=cookie)

Изменение ресурсов ВМ

Чтобы изменить количество ресурсов ВМ, её надо перезагрузить. При запуске задачи на изменение ресурсов ВМ будет перезагружена автоматически. Если задач несколько, то выполнится несколько перезагрузок. Чтобы избежать многократных перезагрузок, рекомендуем использовать отложенные задачи.

Опишите JSON для отложенной задачи на изменение CPU и RAM:

JSON для CPU и RAM

resource_data = json.loads(f'{{
    "cpu_number": {cpu_number},
    "ram_mib": {ram_mib},
    "defer": {{"action": "host_stop"}}
}}')

Опишите JSON для отложенной задачи на изменение дискового пространства:
JSON для диска
```
disk_data = json.loads(f'{{
    "size_mib": {hdd_mib},
    "defer": {{"action": "host_stop"}}
}}')
```

Отправьте запрос на изменение ресурсов:

Изменение CPU, RAM и диска

resource_url = f"https://vm.example.com/v3/host/{host_id}/resource"
host_change_resource = requests.post(url=resource_url, json=resource_data, headers=cookie)
disk_url = f"https://vm.example.com/v3/disk/{disk_id}"
disk_resize = requests.post(url=disk_url, json=disk_data, headers=cookie)

Перезапустите ВМ:

Перезапуск ВМ

host_restart_url = f"https://vm.example.com/vm/v3/host/{host_id}/restart"
restart_data = json.loads('{}')
host_restart = requests.post(url=host_restart_url, json=restart_data, headers=cookie)

В ответе будут получены ID задач task и start_task. Дождитесь завершения start_task.

Может быть полезно

Связанные статьи: