Документация BILLmanager 6 Startup, Advanced
Документация
/
Документация BILLmanager 6 Startup, Advanced
/
Разработчику
/
Взаимодействие через API

Взаимодействие через API

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

Команда для генерации секретного ключа
pwgen -s 16 1

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

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

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

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

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

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

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

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

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

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

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

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

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

URL-адрес платежа
https://billdomain.com/billmgr#/?func=payment.edit&elid=1256&elname=pfx%2F1256&plid=334
  • 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" не используется.

Примеры получения списка WWW-доменов в ISPmanager

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

Утилита curl

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

Утилита mgrctl

/usr/local/mgr5/sbin/mgrctl -m ispmgr webdomain

Язык 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-адрес/ispmgr');

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

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

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

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

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

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

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

Язык PHP

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

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

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

   $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";
               }
           }
       }
   }
?>

Язык 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/ispmgr?authinfo=логин:пароль&func=wwwdomain&out=xml')

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

xmldoc = minidom.parse(res)

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

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

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

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

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

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

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

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

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

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

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

В качестве результата функции описываются только параметры элемента в списке, которые представляют собой один или несколько 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>

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

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

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

В качестве результата функции описываются только параметры объекта. Параметры объекта представляют собой один или несколько 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>

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

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

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

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

Данный результат выдаётся при возникновении ошибки в процессе обработки запроса. В этом случае 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>

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

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

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

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

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

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

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

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

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

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

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

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='

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

Исключив необязательные параметры из запроса ("sfrom", "clicked_button", "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