Как работать с API Billmanager

API — это программный интерфейс, который позволяет управлять любым приложением через набор команд и функций. API Яндекс.Музыки проигрывает музыку прямо на вашем сайте, API Твиттера — дает возможность получать последние записи или фото по тэгам.

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

Документация по API BILLmanager достаточна сложна в освоении. Но есть простой инструмент, вывод которого отображает параметры для любой функции. Если вы хотите стать гуру в работе с API — изучите документацию. Если для вас главное выполнить задачу и получить результат в короткий срок — подойдёт наш инструмент.


Начало работы
Зарегистрируйтесь в BILLmanager или залогиньтесь в существующем аккаунте — для использования API необходима действующая учётная запись.

Инструкции по работе с инструментом API Billmanager:

 

Где взять список параметров API

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

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

Если выделить нужный сервер и выбрать в форме Действие «Удалить», получим вызов для удаления именно выбранного сервера(-ов).

Как получить список VDS

Чтобы получить список VDS, достаточно скопировать в браузер строчку:

https://my.firstvds.ru/billmgr?authinfo=dn4g@firstvds.ru:passwd&func=vds&out=json

Где 

authinfo=USER:PASS — логин (почта) и пароль для входа соответственно.
func=vds — вызов функции и ее аргументов. 
out=json — формат вывода. Их несколько, но мы рекомендуем JSONdata, именно он отображает только запрашиваемые элементы:

Или человекоудобный out=print:

 

Меняем USER:PASS на свой логин и пароль, вставляем получившуюся ссылку в браузер или используем системную утилиту curl

#  curl "https://my.firstvds.ru/billmgr?authinfo=dn4g@firstvds.ru:passwd&func=vds&out=json"

В ответ получим большой JSON-документ, в котором отображается не только информация для отрисовки интерфейса самого биллинга — кнопки, фильтры, предупреждения, оповещения, но и все данные о серверах, расположенных под аккаунтом: IP-адрес, имя, ID VDS в биллинге. Так как нам нужен именно список VDS, обращаем внимание на блок elem:

        "elem":[
            {
                "domain":{
                    "$":"myserver.ru"
                },
                "id":{
                    "$":"8030090"
                },
                "ip":{
                    "$":"37.46.130.128"
                },
                ...
            },
            {
                "domain":{
                    "$":"testserver.ru"
                },
                "id":{
                    "$":"8030079"
                },
                "ip":{
                    "$":"37.46.130.207"
                },
                ...
            }
        ],

 

Список получен. В будущем ID VDS понадобятся для взаимодействия с услугами посредством API.

Если пароль или логин(почта) введены неверно, то в выводе команды мы увидим текст ошибки в блоке param:

"param":[
    {
        "$name":"object",
        "$type":"msg",
        "$":"badpassword"
    },
    {
        "$name":"value"
    }
]
 
 
Как отредактировать форму — изменение параметров сервера
 

В форме можно посмотреть значения параметров VDS или внести и сохранить изменения. Для получения соответствующего вызова API есть переключатели:

  • Пункт Чтение покажет, как вывести текущие параметры сервера на экран — вернёт JSON-запрос с текущими параметрами VDS. 
  • Пункт Запись покажет, список параметров, используемых функцией vds.edit. При этом все ручные изменения полей и «ползунков» отобразятся в ее выводе.   

 

Рассмотрим изменение доменного имени VDS. Для этого в браузере перейдём во вкладку Товары → Виртуальные серверы , выберем нужный и кликнем по кнопке Изменить. Далее нажмём кнопку API и выберем пункт Запись.

В нашем примере за доменное имя отвечает параметр domain. Таким образом, в предложенном запросе, в пункте domain= меняем имя на нужное и выполняем запрос:

https://my.firstvds.ru/billmgr?authinfo=dn4g@firstvds.ru:passwd&func=vds.edit&elid=7588080&processingmodule=783&opendate=2018-08-04&expiredate=2018-12-20&scheduledclose=off&ip=149.154.66.7&domain=sweetvds1.com&password=A4YW46oXt16a&username=team&userpassword=cwC3288lVgFK&panelid=17096&ostempl=ISPsystem__Debian-8-x86_64&serverid=vm7550539&recipe=ISPsystem__ispmanager.sh&monthly126=&quarterly126=&semiannual126=&annually126=&change_disc_size=off&addon_14338=82&addon_42016=off&addon_14339=21&addon_14340=1&addon_14341=0&addon_14337=23739&note=&sok=ok&out=json

Если в  результате выполнения скрипта последует ответ ОК, то доменное имя VDS будет изменено. В случае ошибки API вернёт её текст. 

Работа с циклами
Удалить VDS, добавить памяти или ядер процессора можно и без использования API Billmanager. Но если возникла потребность заказать 10, 100 VDS или массово изменить параметры серверов — процесс может затянуться на несколько часов. В программировании для подобных случаев, где совершается множество однотипных действий, принято использовать циклы.


Например, нам требуется купить 32 сервера VDS-KVM-Старт. Переходим в Виртуальные серверы — Заказать, выбираем в следующей форме тариф. Кликаем по инструменту API, в поле Действие для объекта выбираем Запись:

В появившейся форме будет набор всех указанных параметров для заказа VDS через API Billmanager:

https://my.firstvds.ru/billmgr?authinfo=dn4g@firstvds.ru:passwd&func=vds.order.param&elid=&domain=&datacenter=6&period=1&pricelist=56324&skipbasket=off&ostempl=ISPsystem__CentOS-7-amd64&recipe=null&addon_56329=93&addon_56336=off&addon_56330=21&addon_56331=1&addon_56332=0&addon_56328=56334&licence_agreement=off&sok=ok&out=json

Чтобы сразу оплатить VDS с лицевого счета, минуя корзину, меняем skipbasket=off на skipbasket=on.  

Чтобы не вводить эти URL каждый раз в браузере, мы можем использовать curl и цикл for:

for i in {1..32}; do  curl "https://my.firstvds.ru/billmgr?authinfo=dn4g@firstvds.ru:passwd&func=vds.order.param&elid=&domain=sweet-server.$i&datacenter=6&itemtype=3&period=1&pricelist=56324&skipbasket=off&ostempl=ISPsystem__CentOS-7-amd64&recipe=null&addon_56329=93&addon_56336=off&addon_56330=21&addon_56331=1&addon_56332=0&addon_5”; done

 

В этом примере цикл будет выполнен 32 раза, и имя каждой VDS будет иметь порядковый номер от 1 до 32. Весь процесс займёт около минуты вместо пары часов.

Чтобы работать с API Billmanager было ещё удобнее, можно использовать готовые скрипты на различных языках программирования. Так процедура будет выглядеть на PHP:

<?php

$username="dn4gg";
$password="AlloSupport";

$billmgr_auth = file_get_contents("https://my.firstdvs.ru/billmgr?out=json&func=auth&username=$username&password=$password");
$billmgr_arr = json_decode($billmgr_auth, true);
$session_id=$billmgr_arr['doc']['auth']['$id'];

$quantity=32;
for ($i = 0; $i <= $quantity; $i++){
file_get_contents("https://my.firstvds.ru/billmgr?auth=$session_id&func=vds.order.param&elid=&domain=sweet-server.$i&datacenter=6&itemtype=3&period=1&pricelist=56324&skipbasket=off&ostempl=ISPsystem__CentOS-7-amd64&recipe=null&addon_56329=93&addon_56336=off&addon_56330=21&addon_56331=1&addon_56332=0&addon_5");
}

?>

 

А так на Python:

#!/usr/bin/python
# -*- coding: utf-8 -*-

import requests

username="dn4gg"
password="AlloSupport"

def handle_billmgr_response(response):
    if not response.ok:
        raise ValueError("""Billmgr api returned bad status code: {}""".format(response.status_code))
    try:
        data = response.json()
    except:
        raise ValueError("""Billmgr api returned an unknown response: {}""".format(response.text))
    if "doc" not in data:
        raise ValueError("""Billmgr api returned an unknown error""")
    if "error" in data["doc"]:
        raise ValueError("""Billmgr returned an error: {}""".format(data["doc"]["error"]["msg"]["$"]))
    return data

auth_response = requests.get("""https://my.firstvds.ru/billmgr?out=json&func=auth&username={}&password={}""".format(username, password))
auth_data = handle_billmgr_response(auth_response)
session_id=auth_data['doc']['auth']['$id']

for i in range(32):
    api_url ="""https://my.firstvds.ru/billmgr?auth={}
    &func=vds.order.param
    &elid=&
    domain=sweet-server.{}
    &datacenter=6
    &itemtype=3&
    period=1
    &pricelist=56324
    &skipbasket=off
    &ostempl=ISPsystem__CentOS-7-amd64
    &recipe=null
    &addon_56329=93
    &addon_56336=off
    &addon_56330=21
    &addon_56331=1
    &addon_56332=0
    &addon_5""".format(session_id, i)
    r = requests.get(api_url)
    handle_billmgr_response(r)

 

Как масштабировать серверы на гибких тарифах

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

Запрос будет вида:

https://my.firstvds.ru/billmgr?authinfo=dn4g@firstvds.ru:passwd&func=vds.edit&elid=8129505&showorderinfo=on&ip=188.120.242.222&domain=api.gromovich&password=A7$%TDCKe&username=dn4g&userpassword=ekFi7gfioTF6&ostempl=ISPsystem__Debian-8-x86_64&serverid=vm8129466&recipe=null&needreboot=on&reboot=off&change_disc_size=off&addon_41221=4&addon_41221_show_reboot_warn=on&addon_41222=4&addon_41222_show_reboot_warn=on&addon_41223=20&addon_41225=93&addon_41226=21&addon_41227=2&addon_41227_show_reboot_warn=on&addon_41228=0&addon_42444=24&addon_41224=41230&addon_54664=54665&sok=ok&out=json'

Где перечисляются параметры сервера. Описание параметров находятся в выводе API:

В примере выше значение addon_41222 указано 4 — это значит, что количество оперативной памяти будет равным четырём гигабайтам. Если параметры процессоров, ОЗУ или количество IP-адресов будут изменены, то потребуется перезагрузка сервера. В качестве подтверждения установите галочку или выставите параметр reboot со значением on. Изменить размер диска с клиентской учетной записи невозможно, так как перед этим требуется изменить его размер в VMmanager. Такие права есть только у сотрудников технической поддержки.

 

Как удалить VDS

Имея статус реселлера, вы можете удалить все VDS, к которым имеете доступ. 

При удалении VDS вы будете работать со списками и массивами данных  — для этого удобнее использовать терминал (консоль), в частности системную утилиту curl:


Потребуется указать лишь ID сервера, в выводе выше это 8037665.

#curl “https://my.firstvds.ru/billmgr?authinfo=dn4g@firstvds.ru:passwd&&func=vds.delete&elid=8037665&out=json”

Если все данные введены верно, то в результате out=json будет:

{

    "doc":{

        "ok":{            

        }

        ...

    }

}

Или пробел при использовании out=JSONdata.

Если вместо ok вы видите error, значит возникла ошибка. Например, при неправильно указанном введенном пароле будет Invalid username or password, или пустые поля при отсутствии VDS в активных услугах и корзине.

Для удаления VDS без статуса реселлера понадобится позвонить в техническую поддержку с проверенного номера телефона или подтвердить свои права на аккаунт по смс. Ввели эти ограничения в целях безопасности: если пароль будет скомпрометирован и доступ к Личному кабинету получат посторонние лица, они не смогут удалить ваши VDS.

 

Как сменить сервера имён домена

Использовать API можно не только для работы с VDS, но и при работе с другими услугами в биллинге. Рассмотрим смену серверов имён домена.

Для этого используется функция domain.ns. Требуется указать ID домена (elid) и серверы имён, начиная с ns0.
elid=4013564&ns0=dns1.yandex.net&ns1=dns2.yandex.net&ns2=&ns3=&ns_additional=&sok=ok&out=json'

 

Таким образом, всё, что можно сделать через браузер можно осуществить и через API Billmanager. Часто это будет быстрее, а благодаря возможностям инструмента API проще и нагляднее.