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

О работе с API DNSmanager 6 см. в статье Взаимодействие через API документации DNSmanager 6.

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

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

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

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

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

[https://IP-адрес:1500/ispmgr?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/ispmgr?auth=номер_сессии&out=xml&func=функция&параметр1=значение&параметр2=значение|https://IP-адрес:1500/ispmgr?auth=номер_сессии&out=xml&func=функция&параметр1=значение&параметр2=значение] ...

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

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

В данном примере URL содержит внутренние имя панели управления и может принимать следующие значения

ispmgr — ISPmanager
billmgr — BILLmanager
vmmgr — VMmanager KVM (или Cloud)
vemgr — VMmanager OVZ
dcimgr — DCImanager
dnsmgr — DNSmanager
ipmgr — IPmanager
core — COREmanager
xxxx — любое произвольное имя продукта который вы можете создать самостоятельно на базе COREmanager

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

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

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

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

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

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

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

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

Пользователь, которым нужно авторизоваться, имеет логин vasya.

Авторизационные данные администратора ISPmanager пусть будут такие: пользователь root, пароль secret

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

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

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

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

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

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

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

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

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

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

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

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

Для того чтобы получать результаты выполнения функций или ошибки на родном языке, необходимо к запросу добавить параметр lang=язык (например, lang=ru или lang=en). В случае если будет указан не существующий язык будет использоваться тот который используется в панели управления по умолчанию, обычно это en (английский язык)

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

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

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

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

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

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

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

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

Примеры получения списка 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|http://perldoc.perl.org/functions/qw.html] (fatalsToBrowser);
[print|http://perldoc.perl.org/functions/print.html]  "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|http://perldoc.perl.org/functions/die.html]  $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|http://perldoc.perl.org/functions/push.html]  @sites, $_->textContent;
}

# выведем результат на экран
for( [sort|http://perldoc.perl.org/functions/sort.html]  @sites ){
	[print|http://perldoc.perl.org/functions/print.html]  $_."<br>\n";
}

Язык PHP

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

<?php
   $result = "";
   $fh = [fopen|http://www.php.net/fopen] ( "http://IP-ADDR/ispmgr?authinfo=логин:пароль&out=xml&func=wwwdomain", "r" );
   while( $data = [fread|http://www.php.net/fread] ( $fh, 4096 ) ){
     $result .= $data;
   }
   [fclose|http://www.php.net/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.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-запрос — это выполнить нужное действие в интерфейсе панели и посмотреть функцию и параметры в логе. Как это сделать:

Откройте лог-файл панели с помощью команды tail:
```
tail -f /usr/local/mgr5/var/XXXmgr.log | grep Request
```
Пояснения
XXX — это короткое имя панели. Например: bill, isp, vm, dci.
Выполните требуемое действие в интерфейсе панели. При этом в открытом лог-файле будет видна выполняемая функция и её параметры: подсвечивается зелёным цветом, начинается с 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>=<значение>...

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