В статье описаны методы вызова функций панели управления с помощью API.

Методы HTTP-запросов

Поддерживаются методы "GET" и "POST".

Методы авторизации

Авторизация обязательна перед вызовом функций панели управления.

Авторизация с использованием уникального номера сессии

Этот метод наиболее подходит для использования панели управления через браузер или для скриптов, которые обращаются к ней неоднократно.
Авторизация происходит путём обращения по следующему URL:

https://IP-адрес:1500/billmgr?out=xml&func=auth&username=имя_пользователя&password=пароль
BASH

После этого панель управления вернёт либо сообщение об ошибке, либо XML-документ следующего вида:

<?xml version="1.0" encoding="UTF-8"?>
<doc ...>
<auth id="номер сессии" level="уровень доступа">номер сессии</auth>
...
</doc>
BASH


Сессия привязывается к IP-адресу. В дальнейшем необходимо передавать полученный номер сессии с каждым запросом к панели управления в параметре "auth":

https://IP-адрес:1500/billmgr?auth=номер_сессии&out=xml&func=функция&параметр1=значение&параметр2=значение...
BASH

Номер сессии хранится в течение часа со времени последнего запроса. Если в течение часа не было выполнено никаких запросов, необходимо заново пройти авторизацию.
Уровень доступа определяет права, с которыми авторизовался пользователь. Рекомендуется проверять его на соответствие ожидаемому, чтоб избежать сбоев в работе скрипта.

Авторизация с использованием authinfo

Этот метод авторизации удобен для удалённого единичного обращения к панели управления. В отличии от предыдущего примера, вместо параметра "auth" с номером сессии можно передать параметр "authinfo" и указать в нём сразу имя пользователя и пароль, под которыми будет выполнена операция, например:

https://IP-адрес:1500/billmgr?authinfo=admin1:mypasswd&out=xml&func=функция&параметр1=значение&параметр2=значение...
BASH

Этот метод авторизации является разовым, то есть необходимо передавать параметр "authinfo" с каждым запросом к панели управления.

Авторизацию через "authinfo" можно ограничить "белым списком" IP-адресов и/или сетей. "Белый список" можно настроить через параметры "RestrictAuthinfoRange" и "Option RestrictAuthinfo" конфигурационного файла или через настройки авторизации.

Сквозная авторизация по ключу

Используется для реализации сквозной авторизации пользователя в панели управления из других систем провайдера при помощи только логина или пароля администратора.

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

Команда для генерации секретного ключа

pwgen -s 16 1
CODE

Например, получили строку "1234567890qwertyuiop".

Пользователь, под которым необходимо авторизоваться, имеет логин "vasya".

Авторизационные данные администратора BILLmanager, например, пользователь "root" с паролем "secret".

Далее скрипту необходимо выполнить следующий запрос:

https://URL/billmgr?out=xml&authinfo=root:secret&func=session.newkey&username=vasya&key=1234567890qwertyuiop
BASH

В ответ будет либо "ok", либо ошибка.

Если получен "ok", то пользователя, которого нужно авторизовать, необходимо перенаправить на следующий URL:

https://URL/billmgr?func=auth&username=vasya&key=1234567890qwertyuiop&checkcookie=no
BASH

После перехода по данному URL пользователь будет авторизован в панели управления, а ключ удалён.

Задание ключа возможно с любого IP-адреса. IP-адрес не привязывается к номеру сессии. Ключ действителен один раз. Ограничение на вход с определённых IP-адресов не учитывается.

Получение данных из URL

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

Например, URL-адрес для конкретного платежа. Перейдите в раздел Клиенты → Клиенты → выберите клиента → кнопка Платежи → выберите платёж → кнопка Изменить. URL-адрес формы изменения платежа будет иметь вид:

URL-адрес платежа

https://billdomain.com/billmgr#/?func=payment.edit&elid=1256&elname=pfx%2F1256&plid=334
CODE
  • func=payment.edit — функция для изменения объекта, просмотра его параметров и создания нового объекта (платежа)
  • plid — id клиента
  • elid — id платежа
  • elname — номер платежа (наименование платежа)

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

Кнопка в интерфейсе Dragon

Вызов функций с правами другого пользователя

Обращение к какой-либо функции панели управления с правами другого пользователя осуществляется путём добавления к URL дополнительного параметра "su=логин_пользователя". Администратор сервера может вызывать функции с правами любых пользователей, реселлер — только с правами своих пользователей. Для всех остальных эта возможность запрещена.

Получение результатов на родном языке

Получение результатов выполнения функции или ошибки на родном языке осуществляется путём добавления к URL дополнительного параметра "lang", например "lang=ru" или "lang=en". В случае, если указан несуществующий язык, то будет использован язык, который используется в панели управления по умолчанию.

Формат вывода результатов выполнения функций

Панель управления предоставляет возможность получения результата выполнения своих функций в формате XML, текстовом формате и в формате JSON. Указание желаемого параметра осуществляется путём добавления дополнительного параметра "out=имя_формата".

Возможные значения параметра out:

  • xml — данные будут возвращены в формате XML (без пагинации и фильтра).
  • devel — XML, в котором дополнительно присутствуют данные, описывающие интерфейс пользователя (полезно для отладки своих плагинов).
  • text — данные в текстовом формате (без пагинации и фильтра)
  • sjson — данные в формате JSON.
  • json — аналогично sjson, только Pretty Print (полезно для отладки).
  • JSONdata — аналогично json, но без описаний интерфейса, только данные (без пагинации и фильтра).
  • xjson — аналогично формату вывода по умолчанию (html) только в формате JSON (рекомендуется для создания собственных тем оформления).
  • print — html, пригодный для печати. Работает только для списков данных.

Если параметр "out" отсутствует, то считается, что данные предназначены для браузера и они преобразуются в html.

Локальные обращения к панели управления

При локальных обращениях к панели управления из скриптов или shell удобнее всего пользоваться утилитой "mgrctl", которая имеет ряд преимуществ:

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

Подтверждение операции

Параметр "sok=ok" в запросе эмулирует нажатие на кнопку подтверждения действия (Ок, Применить, В корзину и т.д.) для отправки различных форм в интерфейсе платформы BILLmanager. Например, редактирование тарифного плана.

Отправка запроса без параметра "sok=ok" равносильна простому открытию формы. Чтобы применить переданные значения, добавьте параметр "sok=ok" в запросе.

Не все функции, которые что-то изменяют являются формами. В таких функциях параметр "sok=ok" может не использоваться.

В запросах, направленных на получение текущих значений, параметр "sok=ok" не используется.

Примеры получения списка тарифов

В качестве примера рассматривается получение списка тарифов. Все остальные функции можно вызывать аналогичным образом.

Утилита curl

curl -k -s "https://IP-адрес:1500/billmgr?authinfo=логин:пароль&out=xml&func=pricelist"
BASH

Утилита mgrctl

/usr/local/mgr5/sbin/mgrctl -m billmgr pricelist
BASH

Язык Perl

Для обращения по URL из Perl необходимо установить библиотеку LWP. Для работы с XML-документами требуется библиотека XML::LibXML.

#!/usr/bin/perl -w
use CGI::Carp qw(fatalsToBrowser);
print "Content-type: text/html\n\n";

use LWP::UserAgent;
use XML::LibXML;

my $result;

# Создадим псевдоброузер, который будет "притворяться" MSIE и отправим запрос
$ua = LWP::UserAgent->new;
$ua->agent("Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)");
my $req = HTTP::Request->new(POST => 'https://IP-адрес:1500/billmgr');

$req->content("authinfo=логин:пароль&out=xml&func=pricelist");

my $res = $ua->request($req);

# Проверим результат
if ($res->is_success) {
    $result = $res->content;
} else {
    die $res->status_line."\n";
}

# После этого переменная $result содержит XML документ со списком тарифов,
# либо сообщение об ошибке

my $parser = XML::LibXML->new();
my $doc = $parser->parse_string( $result );
my $root = $doc->documentElement();

# Получим список имён тарифов
my @tariffs = ();
for( $root->findnodes( "elem/name" ) ){
    push @tariffs, $_->textContent;
}

# выведем результат на экран
for( sort @tariffs ){
    print $_."<br>\n";
}
BASH

Язык PHP

Язык PHP предоставляет возможность работы с URL как со стандартными файлами. Для обработки XML-документов используется библиотека "DOM XML".

<?php
   $result = "";
   $fh = fopen( "http://IP-ADDR:1500/billmgr?authinfo=логин:пароль&out=xml&func=pricelist", "r" );
   while( $data = fread( $fh, 4096 ) ){
     $result .= $data;
   }
   fclose( $fh );

   // После этого переменная $result содержит XML-документ со списком тарифов,
   // либо сообщение об ошибке

   $doc = new DOMDocument();
   if( $doc -> loadXML( $result ) ){
       $root = $doc->documentElement;
       foreach ( $root->childNodes as $elem ){
           foreach ($elem->childNodes as $node){
               if( $node->tagName == "name" ){
                   echo $node->nodeValue;
                   echo "\n";
               }
           }
       }
   }
?>
BASH

Язык Python

Для обращения по URL из Python используется, например, библиотека "urllib2". Для работы с XML-документами — библиотека "xml.dom.minidom".

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

from urllib2 import urlopen
from xml.dom import minidom

print "Content-type: text/html\n\n"
res = urlopen('http://IP-ADDR:1500/billmgr?authinfo=логин:пароль&func=pricelist&out=xml')

# После этого переменная res содержит XML-документ со списком тарифов,
# либо сообщение об ошибке

xmldoc = minidom.parse(res)

# Получим список имён тарифов и выводим его результат на экран

for node in xmldoc.getElementsByTagName('elem'):
        for name in node.getElementsByTagName('name'):
                print ('%s<br>' % name.firstChild.nodeValue)
BASH

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

Описание запроса выглядит следующим образом:

Функция: имя функции, которое необходимо передать в параметре "func" запроса.

Параметры: список параметров с кратким описанием. Если функция не принимает никаких параметров, они не указываются в описании. Параметры передаются в формате параметр=значение.

Результат: бывает несколько видов результата в зависимости от типа запрашиваемой функции:

  • список элементов (таблица);
  • список параметров объекта (форма);
  • успешное выполнение операции (действие);
  • сообщение об ошибке.

Список элементов (таблица)

В этом случае XML-документ имеет следующий вид:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <elem>параметры элемента в списке</elem>
    <elem>параметры элемента в списке</elem>
    ...
    <elem>параметры элемента в списке</elem>
</doc>
BASH

В качестве результата функции описываются только параметры элемента в списке, которые представляют собой один или несколько XML-узлов с возможными атрибутами и значениями, так как всё остальное идентично для всех видов списков элементов. Например:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <elem>
        <name>foo.org</name>
        <admin>foo_admin</admin>
        <php/>
        <ssi/>
        <user used="1" limit="10"/>
        <disk used="0" limit="10"/>
        <traf used="3542" limit="8192"/>
    </elem>
    <elem>
        <name>example.com</name>
        <admin>example</admin>
        <cgi/>
        <php/>
        <ssi/>
        <frp/>
        <user used="5" limit="50"/>
        <disk used="39" limit="50"/>
        <traf used="1084" limit="4096"/>
    </elem>
</doc>
BASH

Cписок параметров объекта (форма)

В этом случае XML-документ имеет вид:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <elid>уникальный идентификатор объекта</elid>
    параметры объекта
</doc>
BASH

В качестве результата функции описываются только параметры объекта. Параметры объекта представляют собой один или несколько XML-узлов с возможными атрибутами и значениями, описывающие свойства данного объекта. Всё остальное идентично для всех видов списков элементов.

Например:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <elid>example.com</elid>
    <name>example.com</name>
    <gid>1001</gid>
    <alias>www.example.comtest.example.com</alias>
    <cgi/>
    <phptype>phpcgi</phptype>
    <ssi/>
    <frp/>
    <sslport>443</sslport>
    <alluser>50</alluser>
    <shelluser>5</shelluser>
    <domain>1</domain>
    <base>3</base>
    <traf>4096</traf>
    <disklimit>50</disklimit>
</doc>
BASH

Успешное выполнение операции (действие)

Данный результат выдаётся при создании, изменении, удалении, включении или выключении объекта. В этом случае XML-документ имеет следующий вид:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
    <ok/>
</doc>
BASH

Обратите внимание

Запросы на удаление возвращают код ответа "200", даже если запись не найдена. Чтобы проверить, что запись удалена, вы можете отправить запрос на редактирование записи. Если запись удалена, запрос вернёт сообщение об ошибке.

Сообщение об ошибке

Данный результат выдаётся при возникновении ошибки в процессе обработки запроса. В этом случае XML-документ имеет следующий вид:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <error type="exists" object="user" lang="ru">
    <param name="object" type="msg" msg="Пользователь">user</param>
    <param name="value">ben</param>
    <stack>
      <action level="30" user="jen">admin.edit</action>
    </stack>
    <group>__object__ со значением '__value__' уже существует</group>
    <msg>Пользователь со значением 'ben' уже существует</msg>
  </error>
</doc>
BASH

Список функций и параметров

Описание функций и их параметров панели управления см. в статье BILLmanager API.

Также актуальная информация доступна на мастер-сервере.

Получение полного списка функций BILLmanager:

/usr/local/mgr5/sbin/mgrctl -m billmgr -i
BASH

Получение описания данных вывода списка пользователей (можно использовать параметр "lang" для выбора языка):

/usr/local/mgr5/sbin/mgrctl -m billmgr -i user lang=ru
BASH

Составление API-запроса по логу

Самый простой способ составить API запрос — выполнить требуемое действие в интерфейсе панели и посмотреть функцию и параметры в логе:

1. Откройте лог-файл панели с помощью команды tail:

tail -f /usr/local/mgr5/var/billmgr.log | grep Request
BASH

2. Выполните требуемое действие в интерфейсе панели. При этом в открытом лог-файле будет видна выполняемая функция и её параметры (подсвечивается зелёным цветом, начинается с INFO Request).

Например, создание доменного имени (DNS) в логе ISPmanager выглядит следующим образом:

Feb  6 08:08:07 [2346:23826] core_module INFO Request [188.120.252.33][root] 'clicked_button=ok&email_inaccess=&func=domain.edit&ip=8.8.8.8&ip_existing=&maildomain=off&name=domain.name&ns=ns1.example.com.%20ns2.example.com.&operafake=1486357687433&owner=www%2Droot&owner_admins=off&progressid=false&reversezone=&sfrom=ajax&sok=ok&web_inaccess=&webdomain=off&zoom-ip=&zoom-ns='
BASH

3. На основе полученной в логе функции составьте API-запрос. API-запрос всегда имеет формат "https://<IP или доменное имя>:<основной порт панели>/<короткое имя панели>?func=<функция>&<параметр 1>=<значение>&<параметр 2>=<значение>...".

Исключив необязательные параметры из запроса ("sfrom", "operafake", "progressid", параметры равные знаку * и параметры с пустыми значениями), получим API-запрос:

https://123.123.123.123:443/billmgr?auth=a4b9816e498e&func=domain.edit&ip=8.8.8.8&maildomain=off&webdomain=off&name=domain.name&ns=ns1.example.com.%20ns2.example.com.&owner=www%2Droot&sok=ok&out=xml
BASH