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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примеры получения списка 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>

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

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

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

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

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

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

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

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

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

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

tail -f /usr/local/mgr5/var/dcimgr.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/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