Компания
109,06
рейтинг
14 сентября 2015 в 11:36

Разное → Работа с API Vscale tutorial



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

Vscale API расположен по адресу api.vscale.io/v1.
С его помощью можно выполнять те же действия, что и через панель управления:

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


Взаимодействие осуществляется при помощи стандартных HTTP-запросов. Для обмена данными используется формат JSON.
В случае успешной обработки запроса API вернёт модель объекта в формате JSON. При возникновении ошибки вы получите её код и краткое описание (оно содержится в заголовке Vscale-Error-Message).


Генерация токена



Чтобы начать работу с API, нужно сначала пройти полную процедуру регистрации (включая СМС-подтверждение) и пополнить баланс. Для идентификации пользователей используются токены. Чтобы получить токен, авторизуйтесь в панели управления и перейдите на страницу настроек.
В меню в левой части страницы выберите пункт «Управление токенами».

Нажмите на кнопку «Создать токен». Откроется следующее окно:



Введите краткое описание токена в соответствующее поле. Обратите внимание на флажок «Тип токена». Токены для работы с API подразделяются на два типа:

  • полнофункциональные — могут использоваться со всеми типами запросов для выполнения всех возможных операций;
  • токены read-only — могут использоваться только в GET-запросах; количество выполняемых с ними операций ограничено (например, просмотреть список серверов или доступных конфигураций с таким токеном можно, а вот создать новый сервер — уже нет).


Задав нужные настройки, нажмите на кнопку «Сгенерировать токен». После этого новый токен будет добавлен в список. Его нужно будет передавать во всех запросах в заголовке X-Token.
Вы можете сгенерировать столько токенов, сколько вам нужно для работы. Срок действия токенов неограничен.

Создаём новый сервер



Вспомним порядок действий при создании нового сервера, описанный в предыдущей статье: сначала нужно дать серверу имя, затем выбрать конфигурацию и образ ОС и, наконец, настроить способ доступа. При создании сервера через 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' -d '{"make_from":"ubuntu_14.04_64_002_master","rplan":"medium","do_start":true,"name":"My First Server","keys":[92],"location":"spb0"}' -H 'X-Token:5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'


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

{"name": "Icy-Mysterious", "deleted": null, "rplan": "medium", "made_from": "ubuntu_14.04_64_002_master", "status": "defined", "hostname": "cs14174.vscale.io", "created": "27.08.2015 10:03:07", "ctid": 12600, "private_address": {}, "location": "spb0", "keys": [{"name": "key", "id": 92}], "public_address": {}, "active": false, "locked": true}


Статус текущих операций



Ещё раз просмотрите пример ответа в предыдущем разделе и обратите внимание на поле status. По логике вещей при успешном создании сервера должен быть возвращён статус created, но в приведённом примере соответствующий параметр имеет другое значение — defined. Создавая серверы через графический интерфейс, изменение статусов можно наблюдать в режиме реального времени. В API такой возможности нет, и статусы объектов изменяются не моментально.
Просмотреть информацию о статусе всех текущих операций можно, выполнив GET-запрос на адрес api.vscale.io/v1/tasks:

$ curl -i api.vscale.io/v1/tasks

[{"location": "spb0", "d_insert": "2015-08-28 12:37:48", "id": "3a447f17-3577-4c16-b26c-27bd52faa7c1", "done": false, "scalet": 12835, "error": false, "d_start": "2015-08-28 09:37:48", "method": "scalet_create", "d_end": null}


Из приведённого примера ответа видно, что в текущий момент выполняется операция создания сервера ("method": "scalet_create"), что она ещё не завершена ("done": false) и что при её выполнении не обнаружено никаких ошибок ("error": false).

Операции с серверами



Апгрейд конфигурации



C помощью API всегда можно перейти с текущей конфигурации на более производительную. Изменение конфигурации в меньшую сторону (даунгрейд) невозможно.
При создании нашего тестового сервера мы выбрали конфигурацию medium. Изменим её на large:

$ curl 'https://api.vscale.io/v1/scalets/12600/upgrade'-X POST -d '{"rplan":"large"}' -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'


В случае успешного выполнения запроса будет возвращён ответ с информацией о сервере:

{"private_address": {}, "name": "New-Eyelid", "hostname": "cs12600.vscale.io", "public_address": {"address": "95.213.195.101", "netmask": "255.255.255.0", "gateway": "95.213.195.1"}, "keys": [{"id": 72, "name": "key"}], "made_from": "ubuntu_14.04_64_002_master", "created": "27.08.2015 14:28:51", "ctid": 12600, "status": "updated", "active": true, "locked": false, "deleted": null, "rplan": "medium", "location": "spb0"}


Перезагрузка сервера



Перезагрузка сервера выполняется с помощью PATCH-запроса. Пример:

$ curl -i -X PATCH api.vscale.io/v1/scalets/12600/restart -d '{"id": "12600"}' -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'


В ответе будут перечислены параметры перезагруженного сервера.

Выключение и включение сервера



Выключение и включение сервера также осуществляются с помощью PATCH-запросов:

# выключение сервера

$ curl -i -X PATCH api.vsсale.io/v1/scalets/12600/stop -d '{"id": "12600"}' -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36


#включение сервера 

$ curl -i -X PATCH api.vsсale.io/v1/scalets/12600/start -d '{"id": "12600"}' -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'


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



Чтобы удалить сервер, нужно выполнить DELETE-запрос:

$ curl -i -X DELETE api.vscale.io/v1/scalets/12600 -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'


В ответе будут возвращены параметры удалённого сервера.

Заключение



В этой статье мы рассказали, как можно управлять серверами с помощью API Vscale. Это лишь небольшая часть возможностей API: подробнее обо всех функциях читайте в официальной документации. Мы будем признательны за любую обратную связь.
Предлагаемая вашему вниманию версия API — первая. Если в ней, по вашему мнению, не хватает каких-то функций, сообщите нам об этом. Самые интересные предложения и пожелания мы обязательно учтём в работе над следующей версией.
Автор: @AndreiYemelianov
Селектел
рейтинг 109,06

Комментарии (4)

  • 0
    Ограничения на количество создаваемых серверов, количество обращений к API?
    Пытался использовать ресурсы vscale через API. Больше пяти машин не создается, при этом два из пяти запросов часть машин не создалось.

    Поясните пожалуйста сценарии на которые вы ориентировались при разработке. Я так понимаю, что не получится использовать этот сервис, если мне нужно постоянно создавать машины, проводить какие-либо вычисления в них и удалять их… Сюда же и проблема с тарификацией, если я использовал машину только 20 минут, то платить все равно должен за 1 час. Это нормально, но при большом количестве таких задач — получается очень плохо :).

    Спасибо
    • 0
      а где есть тарификация не за час? у ближайшего конкурента DO такой же минимальный порог.
    • +1
      Заведите одну машину с docker'ом, включайте её, запускайте контейнер, тушите
      • 0
        Да :). Я так и сделал в итоге, подпилил немного и теперь работаю с docker контейнерами. Docker достаточно удобная штука для изолирования среды.

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

Самое читаемое Разное