RU|EN

Помощь

API Billmanager — быстрый способ управления услугами

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

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

У компании ISPsystem, разработчиков BILLmanager, представлена подробная документация по работе через API с описанием каждого раздела и его назначения в BILLmanager.

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

 

С чего начать

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

 

Важные примеры использования API Billmanager:

 

Получить список параметров API

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

При нажатии на иконку откроется форма, в которой можно указать, какое именно нужно действие.

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

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

Получить список VPS

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

https://my.ispserver.ru/billmgr?authinfo=user@mail.ru:passwd&func=vds&out=json

Где

authinfo=USER:PASS — логин (почта) и пароль для входа соответственно.

func=vds — вызов функции и её аргументов.

out=json — способ вывода. Рекомендуемым будет JSONdata, именно он отображает только запрашиваемые элементы:

Или табличный и более понятный вариант: out=print:

Но можно использовать и стандартный json, например через системную утилиту curl:

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

 

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

"elem":[
    {
        "domain":{
            "$":"test.api"
        },

        "id":{
            "$":"8361005"
        },

        "ip":{
            "$":"188.120.228.226"
        },

        "item_cost":{
            "$":"890.0000"
        },

        "name":{
            "$":"VPS-SSD Своя конфигурация v4 #8361005 (188.120.228.226, test.api)"
        },
    }
]

 

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

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

"param":[
    {
        "$name":"object",
        "$type":"msg",
        "$":"badpassword"
    },
    {
        "$name":"value"
    }
]

 

Редактирование форм

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

  • Пункт Чтение дает возможность вывести текущие параметры сервера на экран — т.е. выведет JSON-запрос с текущими параметрами VPS.

  • Пункт Запись показывает список параметров, используемых функцией vds.edit. При этом все изменения полей и «ползунков» в биллинге отобразятся и в её выводе.

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

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

https://my.ispserver.ru/billmgr?authinfo=user@mail.ru:passwd&func=vds.edit&elid=8361005&ip=188.120.228.226&domain=test.api&password=passwd2&username=alexanderelevan&userpassword=passwd3&ostempl=ISPsystem__Ubuntu-16.04-amd64&serverid=vm8361005&recipe=ISPsystem__ispmanager.sh&reboot=off&change_disc_size=off&addon_45343=2&addon_45344=2&addon_45345=20&addon_45347=82&addon_45348=21&addon_45349=2&addon_45350=0&addon_45346=45352&sok=ok&out=JSONdata

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

 

Заказ множества VPS, работа в цикле

В целом, удалять VPS, добавлять оперативной памяти или ядер процессора не составляет труда и без использования API BILLmanager. Но если возникла потребность заказать 30 VPS или массово изменить параметры услуг — процесс может затянуться на продолжительное время. Для совершения множества однотипных действий в программировании принято использовать циклы. Их можно использовать и c API.

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

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

https://my.ispserver.ru/billmgr?authinfo=username:password&func=vds.order.param&elid=&domain=&datacenter=6&period=1&pricelist=69948&skipbasket=off&ostempl=ISPsystem__Ubuntu-16.04-amd64&recipe=null&addon_69952=69958&addon_69953=93&addon_69954=21&addon_69955=1&addon_69956=0&sok=ok&out=json

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

 

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

for i in {1..30}; do  curl "https://my.ispserver.ru/billmgr?authinfo=username:passwd&func=vds.order.param&elid=&domain=test.api.$i&datacenter=6&itemtype=3&period=1&pricelist=56324&skipbasket=on&ostempl=ISPsystem__Ubuntu-16.04-amd64&recipe=null&addon_69952=69958&addon_69953=93&addon_69954=21&addon_69955=1&addon_69956=0&sok=ok&out=json”; done

 

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

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

<?php

$username = "user@mail.ru";
$password = "passwd";

$billmgr_auth = file_get_contents("https://my.ispserver.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 = 30;
for ($i = 0; $i <= $quantity; $i++) {
  file_get_contents("https://my.ispserver.ru/billmgr?auth=$session_id&func=vds.order.param&elid=&domain=test.api.$i&datacenter=6&&itemtype=3&period=1&pricelist=69948&skipbasket=off&ostempl=ISPsystem__Ubuntu-16.04-amd64&recipe=null&addon_69952=69958&addon_69953=93&addon_69954=21&addon_69955=1&addon_69956=0&sok=ok");
}

?>

 

А так на Python:

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

import requests

username="user@mail.ru"
password="passwd"

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.ispserver.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(30):
    api_url ="""https://my.ispserver.ru/billmgr?auth={}
    &func=vds.order.param
    &elid=&
    domain=sweet-server.{}
    &datacenter=6
    &itemtype=3&
    period=1
    &pricelist=69948
    &skipbasket=off
    &ostempl=ISPsystem__Ubuntu-16.04-amd64
    &recipe=null
    &addon_69952=69958
    &addon_69953=93
    &addon_69954=21
    &addon_69955=1
    &addon_69956=0
    &sok=ok""".format(session_id, i)
    r = requests.get(api_url)
    handle_billmgr_response(r)

 

Редактировать параметры сервера на тарифе «Своя конфигурация»

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

Запрос будет выглядеть так:

https://my.ispserver.ru/billmgr?authinfo=user@mail.ru:passwd&func=vds.edit&elid=8361005&showorderinfo=on&ip=188.120.228.226&domain=test.api&password=yJMdsfvKrI7igm2&username=user&userpassword=tWz6dsfdoOPETU1&ostempl=ISPsystem__Ubuntu-16.04-amd64&serverid=vm8361005&recipe=ISPsystem__ispmanager.sh&needreboot=on&reboot=off&change_disc_size=off&addon_45343=3&addon_45343_show_reboot_warn=on&addon_45344=8&addon_45344_show_reboot_warn=on&addon_45345=20&addon_45347=82&addon_45348=21&addon_45349=1&addon_45350=0&addon_45346=45352&sok=ok&out=json

В запросе перечислены параметры сервера. Описание параметров, чтобы не запутаться, есть в выводе API:

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

 

Удаление VPS

Если у вас много VPS, вы можете удалить все VPS, которые соответствуют заданным вами параметрам.

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

Для удаления требуется указать лишь ID сервера, в нашем случае это 8361005.

#curl "https://my.ispserver.ru/billmgr?authinfo=user@mail.ru:passwd&func=vds.delete&elid=8361005&out=json"

 

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

{
    "doc":{
        "ok":{
        }
        ...
    }
}

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

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

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

 

Смена NS у домена

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

Для этого используется функция domain.ns. Требуется указать ID домена (elid) и серверы имён, начиная с ns0.

elid=6027664&ns0=ns1.ispvds.com&ns1=ns2.ispvds.com&ns2=&ns3=&ns_additional=&sok=ok&out=json'

 

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

Назад к категории