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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

https://URL/dnsmgr?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";
имеет встроенную справку по всем функциям и их параметрам актуальную конкретно для используемого сервера.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2. Выполните требуемое действие в интерфейсе панели. При этом в открытом лог-файле будет видна выполняемая функция и её параметры (подсвечивается зелёным цветом, начинается с INFO Request).

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

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