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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   pwgen -s 16 1

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

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

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

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

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

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

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

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

Получение данных из 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 — номер платежа (наименование платежа)

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

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

Обращение к какой-либо функции 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<doc>
    <ok/>
</doc>

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

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

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

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

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

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

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

3. Составьте API-запрос на основе полученной в логе функции. API-запрос всегда имеет формат:

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

    
   Чтобы получить 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

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

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

Утилита curl

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

Утилита mgrctl

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

Язык 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";
}

Язык 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";
               }
           }
       }
   }
?>

Язык 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)