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

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

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

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

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

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

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

Авторизация происходит путём обращения по следующему URL:

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

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

<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" конфигурационного файла или через настройки авторизации.

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

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

Если клиент идентифицирован внешним скриптом, например, билинговой платформой, и его нужно перенаправить в панель управления, минуя шаг авторизации:

  1. Сгенерируйте секретный ключ (любая строка, не менее 16 символов длиной):

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

    pwgen -s 16 1
    CODE

    Например, получили строку "1234567890qwertyuiop". Пользователь, под которым нужно авторизоваться, имеет логин "vasya". Авторизационные данные администратора BILLmanager, например, пользователь "root" с паролем "secret".

  2. Выполните запрос:

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

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

  3. Если ответ "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 — номер платежа (наименование платежа)

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

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

Обращение к какой-либо функции BILLmanager с правами другого пользователя осуществляется путём добавления к 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=логин сотрудника";
  • имеет встроенную справку по всем функциям и их параметрам актуальную конкретно для используемого сервера.

Подробнее см. Утилита mgrctl.

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

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

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

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

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

Переадресация

Чтобы после выполнения запроса (обычно это модифицирующий запрос, который содержит sok=ok) осуществлялась переадресация на другую форму, добавьте к запросу параметр redirect=startform=some.form, где some.form — API-функция нужной формы. Подробнее см. Перечень API-функций.

Значение параметра startform=some.form должно быть URL-encoded, то есть startform%3Dsome.form. 

Пример запроса

https://billdomain.com/billmgr?func=modifying.action&sok=ok&redirect=startform%3Dsome.form
CODE

modifying.action — пример основной функции

some.form — пример функции той формы, на которую нужна переадресация

Для первичных запросов, таких как func=register (регистрация) и func=logon (авторизация), sok=ok не используется, но redirect также отработает.

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

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

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

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

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

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

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

<doc>
    <elem>параметры элемента в списке</elem>
    <elem>параметры элемента в списке</elem>
    ...
    <elem>параметры элемента в списке</elem>
</doc>
BASH

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

<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-документ имеет вид:

<doc>
    <elid>уникальный идентификатор объекта</elid>
    параметры объекта
</doc>
BASH

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

Например:

<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-документ имеет следующий вид:

<doc>
    <ok/>
</doc>
BASH

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

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

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

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

<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 запрос — выполнить действие в интерфейсе BILLmanager и посмотреть функцию и параметры в логе:

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

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

  2. Выполните нужное действие в интерфейсе BILLmanager. В открытом лог-файле будет видна выполняемая функция и её параметры (подсвечивается зелёным цветом, начинается с 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>=<значение>...
    CODE

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

    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

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

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

Утилита 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