ISPmanager API. Основная информация

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

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

ISPmanager 4 предоставляет возможность получения результата выполнения своих функций как в формате XML, так и в текстовом формате.

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

Для получения данных в виде XML необходимо передать панели управления в запросе дополнительный параметр out=xml. При этом результат будет зависеть от типа функции, к которой вы обращаетесь. Так, в случае получения списка элементов функция вернёт XML-документ, состоящий из списка XML-узлов по одному на каждый элемент. Каждый узел в свою очередь состоит из набора узлов, определяющих параметры данного элемента. Например, при обращении к панели управления для получения списка WWW доменов, мы увидим примерно следующее:

# fetch -qo - "http://localhost/manager/ispmgr?func=wwwdomain&out=xml"
<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elem>
		<name>foo.org</name>
		<owner>user</owner>
		<ssl/>
		<php/>
		<ssi/>
	</elem>
	<elem>
		<name>mydomain.com</name>
		<owner>user2</owner>
		<php/>
		<cgi/>
	</elem>
	<elem>
		<name>rotate.com</name>
		<owner>alm</owner>
		<ssl/>
		<php/>
	</elem>
	<elem>
		<name>test.com</name>
		<owner>john</owner>
		<php/>
		<cgi/>
	</elem>
	<elem>
		<name>test.net</name>
		<owner>user</owner>
	</elem>
</doc>
	

При вызове функции, возвращающей набор параметров элемента, например, при его просмотре или редактировании, панель управления вернёт XML-документ со списком узлов, соответствующих параметрам редактируемого элемента. Например, при просмотре свойств WWW домена, мы увидим:

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.edit&elid=mydomain.com&out=xml"
<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elid>mydomain.com</elid>
	<domain>mydomain.com</domain>
	<alias>www.mydomain.com</alias>
	<ip>123.45.67.89</ip>
	<owner>user</owner>
	<admin>webmaster@mydomain.com</admin>
	<index>index.php index.htm</index>
	<php>phpcgi</php>
	<cgi/>
</doc>
	

Если же вы вызываете функцию, которая должна произвести какое-то действие, например, удалить WWW домен, панель управления вернёт XML-документ об успешном выполнении операции

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=mydomain.com&out=xml"
<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<ok>restart</ok>
</doc>
	

или сообщение об ошибке

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=abrakadabra&out=xml"
<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<error>abrakadabra not found.</error>
</doc>
	

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

Для получения данных в текстовом виде необходимо передать панели управления в запросе дополнительный параметр out=text. При этом результат также будет зависеть от типа функции, к которой вы обращаетесь. Так, в случае получения списка элементов функция вернёт список строк, каждая из которых соответствует одному элементу и состоит из набора параметров этого элемента. Например, при обращении к панели управления для получения списка WWW доменов, мы увидим примерно следующее:

# fetch -qo - "http://localhost/manager/ispmgr?func=wwwdomain&out=text"
name=foo.org owner=user ssl php ssi
name=mydomain.com owner=user2 php cgi
name=rotate.com owner=alm ssl php
name=test.com owner=john php cgi
name=test.net owner=user
	

При вызове функции, возвращающей набор параметров элемента, например, при его просмотре или редактировании, панель управления вернёт список параметров элемента, по одному на каждую строчку. Например, при просмотре свойств WWW домена, мы увидим:

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.edit&elid=mydomain.com&out=text"
elid=mydomain.com
domain=mydomain.com
alias=www.mydomain.com
ip=123.45.67.89
owner=user
php=phpcgi
admin=webmaster@mydomain.com
index=index.php index.htm
cgi
	

Если же вы вызываете функцию, которая должна произвести какое-то действие, например, удалить WWW домен, панель управления в случае успешного выполнения операции вернёт

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=mydomain.com&out=text"
OK
	

или сообщение об ошибке

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=abrakadabra&out=text"
ERROR: abrakadabra not found.
	

Порядок описания функций ISPmanager

Описание функций ISPmanager построено следующим образом:

Функция: имя функции, которое необходимо передать в параметре func запроса.

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

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

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

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

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

В этом случае 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>

Если при этом требуется перезагрузка web-сервера, то

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<ok>restart</ok>
</doc>

Для перезагрузки web-сервера нужно обратиться по следующему URL:

http://IP-адрес/manager/ispmgr?out=xml&func=restart

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

Данный результат выдаётся возникновении ошибки в процессе обработки вашего запроса. В этом случае XML документ имеет вид:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<error>сообщение об ошибке.</error>
</doc>