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

Материал из ISPWiki

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

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

Содержание

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

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

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

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

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

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

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

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

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

Номер сессии может быть передан через COOKIE <имя панели>ses5 (для CORE - "coreses5"). Если панель - BILLmanager, используйте для cookie имя "billmgr4".

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

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

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

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

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

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

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

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

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

https://IP-адрес:1500/core?out=xml&func=session.newkey&username=vasya&key=1234567890qwertyuiop

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

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

https://IP-адрес:1500/core?func=auth&username=vasya&key=1234567890qwertyuiop

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

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


!!!ВАЖНО!!!

  https://IP-адрес:1500/core

Используется для панелей пятого поколения. Для панелей четвертого поколения нужно использовать

  https://IP-адрес:1500/manager

Возможные проблемы

Ошибка:	Пожалуйста, включите cookie и попробуйте ещё раз

Добавьте в запрос параметр checkcookie=no, это отключит проверку cookie.

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

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

Утилита 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-узлов по одному на каждый элемент. Каждый узел в свою очередь состоит из набора узлов, определяющих параметры данного элемента.

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

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

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

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

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

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

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

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

Была ли эта информация полезной? Да | Нет
Личные инструменты