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

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

Управление авторизацией

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

Вы можете авторизоваться одним из методов:

• сессионная авторизация;
• авторизация с использованием функции authinfo;
• сквозная авторизация по ключу.

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

Сессионная авторизация

Используйте метод:

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

1. Отправьте GET-запрос:
   Общий вид запроса:

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

   Подробнее

   • IP-адрес:1500 — IP-адрес и порт подключения сервера с платформой. URL содержит внутренние имя панели управления и может принимать следующие значения:
     • billmgr — BILLmanager или Clouden;
     • vmmgr — VMmanager KVM или Cloud;
     • vemgr — VMmanager OVZ;
     • dcimgr — DCImanager;
     • ipmgr — IPmanager;
     • dnsmgr — DNSmanager;
     • core — COREmanager;
   • out=xml — формат ответа;
   • func=auth — функция авторизации;
   • username=имя_пользователя — имя пользователя в BILLmanager;
   • password=пароль — пароль пользователя.
2. Получите XML-ответ:
   Общий вид ответа:

   <doc>
       <auth id="номер сессии" level="уровень доступа">номер сессии</auth>
   ...
   </doc>

3. Используйте полученный идентификатор в последующих запросах:
   Общий вид запроса:

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

Сессия действует один час с момента последнего запроса. Если в течение часа не было запросов, авторизация становится недействительной — пройдите авторизацию повторно.

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

Используйте метод:

• для разовых запросов к платформе;
• при удалённом доступе к платформе без необходимости поддержания сессии.

Отправьте GET-запрос:

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

Особенности метода:

• метод авторизации является разовым — передавайте параметр authinfo в каждом запросе к платформе. Сессия не создаётся и не поддерживается;
• авторизацию через authinfo можно ограничить определёнными IP-адресами и сетями.  Для этого настройте "белый список" доверенных сетей:
  • через параметры RestrictAuthinfoRange и Option RestrictAuthinfo конфигурационного файла;
  • через настройки авторизации.

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

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

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

1. Сгенерируйте секретный ключ. Длина ключа должна быть не менее 16 символов:

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

   pwgen -s 16 1

   Пример полученного ключа: 1234567890qwertyuiop

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

   Общий вид запроса:

   https://IP-адрес:1500/billmgr?out=xml&authinfo=root:secret&func=session.newkey&username=alex&key=1234567890qwertyuiop

   Подробнее

   • IP-адрес:1500 — IP-адрес и порт подключения сервера с платформой;
   • authinfo=root:secret — учётные данные администратора BILLmanager;
   • func=session.newkey — функция создания сквозного ключа авторизации;
   • username=alex — логин пользователя, который будет авторизован;
   • key=1234567890qwertyuiop — сгенерированный ключ.
3. Получите ответ. Если ответ ok, операция успешна. В случае ошибки проверьте права администратора и корректность параметров.
4. Если ответ ok, перенаправьте пользователя на авторизацию по ключу:
   
   Общий вид запроса:

   https://IP-адрес:1500/billmgr?func=auth&username=alex&key=1234567890qwertyuiop&checkcookie=no

   Подробнее

   • IP-адрес:1500 — IP-адрес и порт подключения сервера с платформой;
   • func=auth — функция авторизации;
   • username=alex — логин пользователя;
   • key=1234567890qwertyuiop — ранее сгенерированный ключ;
   • checkcookie=no — отключение проверки cookies.

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

Ключ является одноразовым. Установить ключ можно с любого IP-адреса. При использовании метода для пользователя действуют ограничения на вход по IP-адресу. Авторизоваться с неразрешенного IP, используя ключ, нельзя.

Формат запросов и результатов

Формат запросов к API BILLmanager

Для отправки API-запросов к BILLmanager используйте HTTP-методы GET и POST.

Запрос состоит из следующих частей:

• функция — имя функции, которое необходимо передать в параметре func запроса. Например, pricelist, auth, session.delete;
• параметры — список параметров в формате параметр=значение. Например, elid=12345.

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

В зависимости от типа функции существует несколько видов результата:

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

Формат вывода результатов

Вы можете получить вывод функции в формате XML, текстовом формате и в формате JSON. Чтобы задать формат получения результатов, укажите в запросе параметр out=имя_формата.

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

Если параметр out не указан, платформа возвращает ответ в формате HTML, предназначенном для отображения в браузере.

Особенности работы

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

Чтобы обратиться к функции BILLmanager от имени другого пользователя, добавьте к запросу параметр su=логин_пользователя.

Права доступа:

• администратор платформы — может вызывать функции с правами любого пользователя платформы;
• клиент с полными правами — может вызывать функции только с правами своих клиентов;
• остальные роли — не имеют права использовать параметр su.

https://IP-адрес:1500/billmgr?auth=токен&func=user.info&su=целевой_пользователь&out=xml

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

Чтобы получить результат выполнения функции или сообщение об ошибке на определённом языке, добавьте к запросу параметр:  lang=код_языка. Например lang=ru или lang=en. Если указан несуществующий или неподдерживаемый код языка, будет использован язык по умолчанию.

Локальные обращения к платформе

Чтобы выполнять API-запросы к платформе локально — из скриптов или shell  — рекомендуется использовать утилиту mgrctl. Преимущества mgrctl:

• прямое обращение к ядру платформы — минует веб-сервер, не зависит от его состояния и настроек;
• автоматическая авторизация — запросы выполняются от имени пользователя, запустившего команду. Хранить пароли не требуется. Чтобы выполнить действия от имени другого пользователя используйте параметр su=логин сотрудника;
• встроенная справка — описание всех функций и их параметров, актуальное для используемого сервера.

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

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

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

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

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

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

• функция: имя функции, которое необходимо передать в параметре 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.com test.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>

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

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

Наиболее удобный способ получения актуальной информации — это использование утилиты mgrctl с ключом -i.

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

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

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

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

Как составить API-запрос по логу

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

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

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

   Пояснения

   XXX — это короткое имя панели. Например: bill, isp, vm, dci.

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

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

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

   [https://123.123.123.123:443/ispmgr?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|https://123.123.123.123:443/ispmgr?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]