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

Материал из ISPWiki

(Перенаправлено с API result is "error")
Перейти к: навигация, поиск

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

Содержание

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

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

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

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

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

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

<?xml version="1.0" encoding="UTF-8"?>
<doc>
<auth id="номер сессии"/>
</doc>

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

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

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

  • ispmgr - ISPmanager
  • billmgr - BILLmanager
  • vdsmgr - VDSmanager
  • dsmgr - DSmanager
  • dnsmgr - DNSmanager
  • ipmgr - IPmanager


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

Данный метод авторизации удобен для удалённого обращения к панели управления. Для вызова какой-либо функции ISPmanager необходимо добавить дополнительный параметр authinfo и указать в нём имя пользователя и пароль, под которыми вы хотите выполнить операцию, например, 

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

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

Авторизация с использованием доверенных IP-адресов

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

TrustIP  IP-адрес  пользователь

В качестве параметра "IP-адрес" необходимо указать адрес сервера, с которого будут приходить запросы к панели управления. В качестве параметра "пользователь" - имя пользователя, с правами которого будут осуществляться операции с панелью управления. Данный параметр является опциональным. Если его нет, запросы будут обрабатываться с правами root для ISPmanager и правами пользователя admin для других панелей управления.

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

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

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

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

Генерируется ключ - любая строка, не менее 16 символов

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

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

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

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

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

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

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

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

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

HTTP или HTTPS?

Так как HTTP является незащищенным протоколом, передавать пароли или номера сессий с его помощью небезопасно. Поэтому панель управления отслеживает, совпадает ли IP-адрес вызывающей стороны с IP-адресом сервера, на котором она расположена, и, если совпадает, то есть в случае локального вызова функций ISPmanager, разрешает использование протокола HTTP. В противном случае разрешается использование только HTTPS и, при попытке обращения к панели управления по протоколу HTTP, будет возвращена ошибка.

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

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


Примеры получения списка WWW доменов в ISPmanager

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

Команда fetch 

fetch -q -o - "http://IP-адрес/manager/ispmgr?out=xml&func=wwwdomain"

Команда curl 

curl -k -s "http://IP-адрес/manager/ispmgr?out=xml&func=wwwdomain"


Язык 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-адрес/manager/ispmgr');
 
$req->content("authinfo=логин:пароль&out=xml&func=wwwdomain");
 
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://127.0.0.1/manager/ispmgr?out=xml&func=wwwdomain", "r" );
   while( $data = fread( $fh, 4096 ) ){
     $result .= $data;
   }
   fclose( $fh );
 
   // После этого переменная $result содержит XML документ со списком WWW доменов,
   // либо сообщение об ошибке
 
   if( $doc = domxml_open_mem( $result ) ){
      $root = $doc->document_element();
      for( $elem = $root->first_child(); $elem; $elem = $elem->next_sibling() ){
         for( $node = $elem->first_child(); $node; $node = $node->next_sibling() ){
            if( $node->node_name() == "name" ){
               echo $node->get_content();
               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://127.0.0.1/manager/ispmgr?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)

Утилита mgrctl

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


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

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

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

  • xml - данные будут возвращены в формате XML,
  • devel - тоже самое, что XML, но в документе будут присутствовать, данные описывающие интерфейс пользователя (полезно для отладки своих плагинов),
  • text - данные в текстовом формате
  • json - данные в формате JSON. http://ru.wikipedia.org/wiki/JSON

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

Вывод результатов выполнения функций в формате 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>

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

Для получения данных в текстовом виде необходимо передать панели управления в запросе дополнительный параметр 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.

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

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

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

Если при этом требуется перезагрузка 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>

Коды ошибок предоставлены в отдельном документе.

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

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


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

Источник — «http://ru.ispdoc.com/index.php/%D0%92%D0%B7%D0%B0%D0%B8%D0%BC%D0%BE%D0%B4%D0%B5%D0%B9%D1%81%D1%82%D0%B2%D0%B8%D0%B5_%D1%87%D0%B5%D1%80%D0%B5%D0%B7_API#.D0.A1.D0.BE.D0.BE.D0.B1.D1.89.D0.B5.D0.BD.D0.B8.D0.B5_.D0.BE.D0.B1_.D0.BE.D1.88.D0.B8.D0.B1.D0.BA.D0.B5»
Была ли эта информация полезной? Да | Нет
Личные инструменты