Vscale API: краткое введение
ВыделеноVscale API расположен по адресу https://api.vscale.io/v1.
С его помощью можно осуществлять те же действия, что и через панель управления:
- создавать и удалять серверы;
- изменять конфигурацию сервера на более производительную ;
- отключать, включать и перезагружать серверы;
- получать информацию о платежах и списаниях со счёта;
- работать с тикет-системой (создавать новые тикеты, отправлять комментарии, закрывать тикеты).
Взаимодействие осуществляется при помощи стандартных HTTP-запросов. Для обмена данными используется формат JSON.
В случае успешной обработки запроса API вернёт модель объекта в формате JSON. При возникновении ошибки вы получите её код и краткое описание (оно содержится в заголовке Vscale-Error-Message).
Документация с подробным описанием функций API опубликована здесь.
Генерация токена
Чтобы начать работу с API, нужно сначала пройти полную процедуру регистрации (включая СМС-подтверждение) и пополнить баланс. Для идентификации пользователей используются токены. Чтобы получить токен, авторизуйтесь в панели управления и перейдите на страницу настроек.
В меню в левой части страницы выберите пункт “Управление токенами”.
Нажмите на кнопку “Создать токен”. Откроется следующее окно:
Введите краткое описание токена в соответствующее поле. Обратите внимание на флажок “Тип токена”. Для работы с API используются токены двух типов:
- полнофункциональные — могут использоваться со всеми типами запросов для выполнения всех возможных операций;
- токены read-only — могут использоваться только в GET-запросах; количество выполняемых с ними операций ограничено (например, просмотреть список серверов или доступных конфигураций с таким токеном можно, а вот создать новый сервер — уже нет).
Задав нужные настройки, нажмите на кнопку “Сгенерировать токен”. После этого новый токен будет добавлен в список. Его нужно будет передавать во всех запросах в заголовке X-Token.
Вы можете сгенерировать столько токенов, сколько вам нужно для работы. Срок действия токенов неограничен.
Пример 1 создание нового сервера
Чтобы создать сервер через графический интерфейс, нужно выполнить следующие действия: дать серверу имя, затем выбрать конфигурацию и образ ОС и, наконец, настроить способ доступа. При работе через API все необходимые характеристики сервера передаются в теле запроса. Обязательными для создания сервера параметрами являются следующие:
- make_from — образ ОС, выбранный для установки на сервере: debian_8.1_64_001_master, centos_7.1_64_001_master, ubuntu_14.04_64_002_master (о том, как получить список доступных образов, подробнее читайте здесь):
- rplan — имя конфигурации сервера; из предыдущей статьи вы уже знаете, что мы предлагаем 5 доступных конфигураций. Вот их имена (в порядке возрастания): small, medium,large, huge, monster. Процедура получения списка конфигураций описана в документации к API.
- do_start: true — служебный параметр, указывающий, что сервер нужно запускать сразу же после установки;
- name — имя сервера;
- keys — идентификационный номер SSH-ключа, по которому будет осуществляться доступ на сервер (об управлении SSH-ключами подробнее см. здесь);
- password — пароль (если требуется доступ по паролю)
- locations — дата-центр, в котором будет размещён сервер (на сегодняшний день этот параметр может иметь только одно значение — spb).
Запрос на создание сервера выглядит так:
$ curl -i -X POST 'https://api.vscale.io/v1/scalets' -H 'Content-Type: application/json;charset=UTF-8' -H 'X-Token: 5c21a467f3b37c331e7482599f1e0971c9bedc30258d6977bbd1db2401bb27e8' -d '{"make_from":"ubuntu_14.04_64_002_master","rplan":"medium","do_start":true,"name":"New-Test","keys":[16],"location":"spb0"}'
В случае успешного создания сервера будет возвращён ответ вида:
HTTP/1.1 200 OK {
"status": "defined",
"deleted": null,
"public_address": {},
"active": false,
"location": "spb0",
"locked": true,
"hostname": "cs11533.vscale.io",
"created": "20.08.2015 14:57:04",
"keys": [ { "name": "somekeyname", "id": 16 } ],
"private_address": {},
"made_from": "ubuntu_14.04_64_002_master",
"name": "New-Test",
"ctid": 11,
"rplan": "medium" }
Статус текущих операций
Ещё раз просмотрите пример ответа в предыдущем разделе и обратите внимание на поле status. По логике вещей при успешном создании сервера должен быть возвращён статус created, но в приведённом примере соответствующий параметр имеет другое значение — defined. Создавая серверы через графический интерфейс, изменение статусов можно наблюдать в режиме реального времени. В API такой возможности нет, и статусы объектов изменяются не моментально.
Просмотреть информацию о статусе всех текущих операций можно, выполнив GET-запрос на адрес https://api.vscale.io/v1/tasks:
$ curl -i https://api.vscale.io/v1/tasks -H 'X-Token: 5c21a467f3b37c331e7482599f1e0971c9bedc30258d6977bbd1db2401bb27e8'
Пример 2: апгрейд конфигурации
C помощью API всегда можно перейти с текущей конфигурации на более производительную. Переход на менее производительную конфигурацию (даунгрейд) невозможен.
При создании сервера в предыдущем примере мы выбрали конфигурацию medium. Чтобы изменить её large, нужно отправить следующий запрос:
$ curl 'https://api.vscale.io/v1/scalets/270834/upgrade' -X POST -H 'X-Token: 5c21a467f3b37c331e7482599f1e0971c9bedc30258d6977bbd1db2401bb27e8' --data-binary '{"rplan":"monster"}' -H 'Content-Type: application/json;charset=UTF-8'
Как видно из приведённого примера, в теле запроса было передано имя новой конфигура ции в значении параметра rplan.
В случае успешного выполнения запроса будет возвращён ответ с информацией о сервере:
{"made_from": "ubuntu_14.04_64_002_master",
"location": "spb0",
"active": true,
"created": "20.08.2015 14:57:04",
"name": "New-Test",
"deleted": null,
"tags": [ ],
"keys": [],
"ctid": 11533,
"rplan": "large",
"hostname": "cs11533.vscale.io",
"locked": true,
"public_address": {"netmask": "255.255.255.0", "gateway": "212.92.98.1 ", "address": "212.92.98.194"},
"status": "started",
"private_address": {}}
Пример 3: перезагрузка, включение и выключение сервера
Операции включения, выключения и перезагрузки серверов осуществляются с помощью PATCH-запросов:
# перезагрузка сервера
$ curl -i -X PATCH https://api.vscale.io/v1/scalets/12600/restart -d '{"id": "12600"}' -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'
# выключение сервера
$ curl -i -X PATCH https://api.vsсale.io/v1/scalets/12600/stop -d '{"id": "12600"}' -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'
#включение сервера
$ curl -i -X PATCH https://api.vsсale.io/v1/scalets/12600/start -d '{"id": "12600"}' -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'
Пример 4: удаление сервера
Удаление к серверу осуществляется с помощью DELETE-запроса:
$ curl -i -X DELETE https://api.vscale.io/v1/scalets/12600 -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'
В ответе будут возвращены параметры удалённого сервера.
Заключение
В этой статье мы привели лишь самые простые примеры работы с API. Обо всех функциях и возможностях API можно прочитать в официальной документации. Текущая версия API — первая. Если в ней, по вашему мнению, не хватает каких-либо функций, сообщите нам об этом. Ваши предложения и пожелания мы учтём в работе над второй версией.
tglnkAPI
Войдите в службу, чтобы оставить комментарий.
Комментарии
Комментариев: 4