3
1 ОБЩИЕ СВЕДЕНИЯ
Протокол администрирования из внешних приложений – это прикладной
программный интерфейс (API-интерфейс), предназначенный для получения
информации о текущих настройках MVTS II и их изменения через запросы,
направляемые к web-серверу MVTS II по протоколу SOAP из внешнего приложения.
Для доступа к web-сервису, реализующему программный интерфейс, необходимо
использовать запрос вида https://your_domain/service/?{proto}. В настоящий момент
можно использовать только протокол SOAP, для этого подстроку proto нужно
заменить на ключевое слово soap.
Интерфейс описывается с помощью WSDL 1.1. (файл описания см. раздел 5)
C помощью интерфейса можно осуществлять следующие операции:
1. Выборка записей из БД;
2. Подсчет количества записей в БД;
3. Вставка записей в БД;
4. Изменение записей в БД;
5. Удаление записей из БД;
6. Осуществление вспомогательных операций, требующихся для более удобной
обработки данных БД.
1.1 АВТОРИЗАЦИЯ
Учетные данные клиента для аутентификации и авторизации должны предоставляться
при каждом запросе к сервису.
Для протокола SOAP необходимо в заголовок каждого пакета добавлять имя учетной
записи клиента и ее пароль. См. пример на языке PHP:
$client = new SoapClient(
'https://rtu2/mvtspro/extensions/service/?wsdl',
array(
'timeout' => 1000
)
);
$headers = array();
$headers[] = new
SoapHeader('http://mfisoft.ru/auth','Login','admin');
$headers[] = new
SoapHeader('http://mfisoft.ru/auth','Password','admin');
$client->__setSoapHeaders($headers);
4
1.3 ТИПЫ ПЕРЕДАВАЕМЫХ ДАННЫХ
Наряду с основными типами данных (int, string и др.) при использовании сервиса
применяются и специальные типы, описанные ниже.
1.3.1 COLUMN
Тип COLUMN представляет собой описание ассоциативный массив, с двумя
элементами: name - ID колонки, и value – значение колонки.
Array(
‘name’ => ‘column1’,
‘value’ => ‘value1’
)
1.3.2 ROW
Тип ROW используется для передачи записей таблиц, а так же для передачи
параметров процедурам. Представляет собой ассоциативный массив колонок (типа
COLUMN).
Пример:
Array(
Array(
‘name’ => ‘column1’,
‘value’ => ‘value1’
),
Array(
‘name’ => ‘column2’,
‘value’ => ‘value2’
),
)
1.3.3 ROWSET
Тип ROWSET используется для передачи набора записей. Представляет собой массив
элементов типа ROW.
Пример:
Array(
Array(
Array(
‘name’ => ‘column1’,
‘value’ => ‘value1’
),
Array(
‘name’ => ‘column2’,
‘value’ => ‘value2’
)
),
Array(
Array(
‘name’ => ‘column1’,
‘value’ => ‘value1’
),
Array(
‘name’ => ‘column2’,
‘value’ => ‘value2’
5
)
)
)
1.3.4 SORT
Тип SORT используется для передачи параметров сортировки. Данный тип
представляет собой массив из элементов сортировки, которые, в свою очередь,
являются ассоциативными массивами, состоящими из двух элементов: названия
колонки, и способа сортировки. Существует два способа сортировки: по возрастанию
(asc) и по убыванию (desc).
Пример:
Array(
Array(
‘column’ => ‘num_call’,
‘dir’ => ‘desc’
),
Array(
‘column’ => ‘contr_hi’,
‘dir’ => ‘asc’
)
)
1.3.5 FILTER
Тип FILTER используется для передачи фильтров (параметр p_filter в функциях). Тип
представляет собой ассоциативный массив, структура которого зависит от вида
фильтра.
Первый вид фильтра – условие. Массив FILTER при этом имеет следующую
структуру:
Array(
‘type’ => ‘cond’,
‘column’ => ‘num_call’,
‘operator’ => ‘>’,
‘value’ => ‘1’
)
6
Array(
‘type’ => ‘cond’,
‘column’ => ‘contr_hi’,
‘operator’ => ‘like’,
‘value’ => ‘01%’
),
Array(
‘type’ => ‘cond’,
‘column’ => ‘contr_desc’,
‘operator’ => ‘=’,
‘value’ => ‘Company’
)
)
)
)
‘type’ – вид фильтра, значение agg означает, что вид – объединение условий;
‘operator’ – оператор объединяющий условия. Может принимать следующие
значения: 'and', 'or', 'not_and', ‘not_or';
‘childs’ – параметр представляет собой массив других фильтров первого или
второго вида.
Таким образом, в примере выше получается фильтр: (contr_hi like ‘01%’ )
and (contr_desc = Company ).
1.3.6 AVAILABLE_VALUES
Тип используется для передачи возможных значений колонки. Представляет собой
массив ассоциативных массивов с двумя ключами“k” и “v”:
Array(
Array(
‘k’ => ‘1’,
‘v’ => ‘Yes’
)
)
1.3.7 COLUMN_DESC
Тип COLUMN_DESC используется для передачи описания колонок. Данный тип
представляет собой ассоциативный массив со следующей структурой:
Array(
column_name
not_null
data_type
ctl_type
have_lookup
initial_value
data_mask
title
verify_pattern
transform_pattern
min_val
7
max_val
min_val_exclude
max_val_exclude
delimiter
min_len
max_len
action
character_maximum_length
)
На языке PHP все значения в массиве имеют тип string.
‘column_name’ – внутреннее имя колонки, использующееся для идентификации
колонок;
‘not_null’ – параметр должен иметь значение “true”, если колонка не может
содержать значение NULL;
‘data_type’ – тип данных колонки;
‘ctl_type’ – имя органа управления, который используется в GUI для данной
колонки;
‘have_lookup’ – параметр принимает значение “true”, если колонка имеет
предопределенный список возможных значений, который можно получить функцией
getColumnLookup;
‘initital_value’ – значение по умолчанию, которое получает данная колонка
при добавлении новой записи в GUI;
‘data_mask’ – маска даты, в которой хранится дата в БД (например, YMDhms, где
Y – год, 4 цифры, M – месяц, 2 цифры, D – день, 2 цифры, h – час, 2 цифры, m –
минуты, 2 цифры, s – секунды, 2 цифры);
‘title’ – название колонки, отображающееся в GUI;
‘verify_pattern’ – регулярное выражение для проверки данных на соответствие
списку возможных значений;
‘transform_pattern’ – регулярное выражение для трансформации данных,
введенных через web-интерфейс;
‘min_val’ – минимальное числовое значение колонки;
‘max_val’ – максимальное числовое значение колонки;
‘min_val_exclude’ – параметр равен “true”, если необходимо исключать
минимальное значение из списка возможных;
‘max_val_exclude’ – параметр равен “true”, если необходимо исключать
максимальное значение из списка возможных;
‘delimiter’ – разделитель списка значений в колонке;
‘min_len’ – минимальная длина поля (то есть, минимальное количество знаков,
которые могут содержаться в поле);
‘max_len’ – максимальная длина поля (то есть, максимальное количество знаков,
которые могут содержаться в поле);
‘action’ – права на колонку. Задаются битовой маской, представленной десятичным
числом, где 1 означает права на просмотр, 2 – права на обновление, 4 – права на
добавление данных;
‘character_maximum_length’ - максимальная длина поля, заданная на уровне
БД.
8
2 ДОСТУПНЫЕ ФУНКЦИИ СЕРВИСА
2.1 ВСПОМОГАТЕЛЬНЫЕ ФУНКЦИИ
2.1.1 GETTABLEBYTITLE
2.1.2 DESCRIBECOLUMNS
9
2.1.3 GETCOLUMNLOOKUP
10
p_table_hi (тип string) – идентификатор таблицы, в которую ведется вставка.
p_rowset (тип rowset) – набор строк, которые будут вставлены (см. 1.3.3).
Функция возвращает количество вставленных строк.
11
3 ОПИСАНИЕ ОШИБОК
Для передачи ошибок используется объект SOAP Fault
http://www.w3schools.com/SOAP/soap_fault.asp. Список возможных ошибок включает в
себя ошибки при работе с GUI, ошибки, связанные с неправильным синтаксисом при
создании фильтра и способа сортировки, а также ошибки при указании неправильных
авторизационных данных.
12
4 ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ WEB-СЕРВИСА
4.1 ВЫБОРКА ДАННЫХ ИЗ ТАБЛИЦЫ
В примере делается выборка данных из таблицы зон. Выбираются только зоны с
идентификаторами, начинающимися на test. Для этого необходимо:
1. Создать SOAP-соединение и добавить в заголовки запросов авторизационную
информацию:
$client = new SoapClient(
'https://your_domain/service/?wsdl'
);
$headers = array();
$headers[] = new
SoapHeader('http://mfisoft.ru/auth','Login','admin');
$headers[] = new
SoapHeader('http://mfisoft.ru/auth','Password','admin');
$client->__setSoapHeaders($headers);
13
[character_maximum_length] => 1000
)
Оно означает, что в таблице имеется две колонки с именами zone_id и description.
4. Создать фильтр для выборки:
$filter = Array(
‘type’ => ‘agg’,
‘operator’ => ‘and’,
‘childs’ => Array(
Array(
‘type’ => ‘cond’,
‘column’ => ‘zone_id’,
‘operator’ => ‘like’,
‘value’ => ‘test%’
)
)
)
14
5 SOAP_SERVER.WSDL
WSDL-документ, содержащий необходимые спецификации для клиентской части,
приведен ниже и также доступен по адресу https://your_domain/service/?wsdl.
<?xml version="1.0" encoding="utf-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ns1="http://xml.apache.org/xml-soap"
xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:ns3="http://mfisoft.ru/voip/service/soap"
xmlns:ns="http://schemas.xmlsoap.org/soap/encoding/" name="mvtsii-api"
targetNamespace="http://mfisoft.ru/voip/service/soap">
<wsdl:types>
<s:schema targetNamespace="http://mfisoft.ru/voip/service/soap">
<s:complexType name="rowset">
<s:complexContent>
<s:restriction base="ns:Array">
<s:sequence>
<s:element name="item" type="ns3:row"
maxOccurs="unbounded"/>
</s:sequence>
<s:attribute ref="ns:arrayType"
arrayType="ns3:row[]" />
</s:restriction>
</s:complexContent>
</s:complexType>
<s:complexType name="row">
<s:complexContent>
<s:restriction base="ns:Array">
<s:sequence>
<s:element name="item" type="ns3:column"
maxOccurs="unbounded"/>
</s:sequence>
<s:attribute ref="ns:arrayType"
arrayType="ns3:column[]" />
</s:restriction>
</s:complexContent>
</s:complexType>
<s:complexType name="column">
<s:all>
<s:element name="name" type="s:string"/>
<s:element name="value" type="s:string"/>
</s:all>
</s:complexType>
<s:complexType name="sort">
<s:complexContent>
<s:restriction base="ns:Array">
<s:sequence>
<s:element name="item"
type="ns3:sort_item" maxOccurs="unbounded"/>
</s:sequence>
<s:attribute ref="ns:arrayType"
arrayType="ns3:sort_item[]" />
</s:restriction>
</s:complexContent>
</s:complexType>
<s:complexType name="sort_item">
<s:all>
<s:element name="column" type="s:string"/>
<s:element name="dir" type="ns3:order_type"/>
</s:all>
</s:complexType>
<s:simpleType name="order_type">
<s:restriction base="s:string">
<s:enumeration value="asc"/>
15
<s:enumeration value="desc"/>
</s:restriction>
</s:simpleType>
<s:complexType name="filter_childs_arr">
<s:complexContent>
<s:restriction base="ns:Array">
<s:sequence>
<s:element name="item" type="ns3:filter"
maxOccurs="unbounded"/>
</s:sequence>
<s:attribute ref="ns:arrayType"
arrayType="ns3:filter[]" />
</s:restriction>
</s:complexContent>
</s:complexType>
<s:complexType name="filter">
<s:all>
<s:element name="type" type="s:string"/>
<s:element name="column" type="s:string"
nillable="true"/>
<s:element name="operator" type="s:string"
nillable="true"/>
<s:element name="value" type="s:string"
nillable="true"/>
<s:element name="childs" type="ns3:filter_childs_arr"
nillable="true"/>
</s:all>
</s:complexType>
</s:schema>
</wsdl:types>
<message name="insertRowsetRequest">
<part name="p_table_hi" type="s:string"/>
<part name="p_rowset" type="ns3:rowset"/>
</message>
<message name="insertRowsetResponse">
<part name="result" type="s:integer"/>
</message>
<message name="updateRowsetRequest">
<part name="p_table_hi" type="s:string"/>
<part name="p_rowset" type="ns3:rowset"/>
<part name="p_filter" type="ns3:filter"/>
</message>
<message name="updateRowsetResponse">
<part name="result" type="s:integer"/>
</message>
<message name="deleteRowsetRequest">
<part name="p_table_hi" type="s:string"/>
<part name="p_rowset" type="ns3:rowset"/>
<part name="p_filter" type="ns3:filter"/>
</message>
<message name="deleteRowsetResponse">
<part name="result" type="s:integer"/>
</message>
<message name="selectRowsetRequest">
<part name="p_table_hi" type="s:string"/>
<part name="p_filter" type="ns3:filter"/>
<part name="p_sort" type="ns3:sort"/>
<part name="p_limit" type="s:integer"/>
<part name="p_offset" type="s:integer"/>
</message>
<message name="selectRowsetResponse">
<part name="result" type="s:anyType"/>
</message>
<message name="countRowsetRequest">
<part name="p_table_hi" type="s:string"/>
<part name="p_filter" type="ns3:filter"/>
</message>
<message name="countRowsetResponse">
<part name="result" type="s:integer"/>
</message>
<message name="getTableByTitleRequest">
16
<part name="p_title" type="s:string"/>
</message>
<message name="getTableByTitleResponse">
<part name="result" type="s:string"/>
</message>
<message name="describeColumnsRequest">
<part name="p_table_hi" type="s:string"/>
</message>
<message name="describeColumnsResponse">
<part name="result" type="s:anyType"/>
</message>
<message name="getColumnLookupRequest">
<part name="p_table_hi" type="s:string"/>
<part name="p_column_nm" type="s:string"/>
</message>
<message name="getColumnLookupResponse">
<part name="result" type="s:anyType"/>
</message>
<portType name="servicePortType">
<operation name="insertRowset">
<input message="ns3:insertRowsetRequest"/>
<output message="ns3:insertRowsetResponse"/>
</operation>
<operation name="updateRowset">
<input message="ns3:updateRowsetRequest"/>
<output message="ns3:updateRowsetResponse"/>
</operation>
<operation name="deleteRowset">
<input message="ns3:deleteRowsetRequest"/>
<output message="ns3:deleteRowsetResponse"/>
</operation>
<operation name="selectRowset">
<input message="ns3:selectRowsetRequest"/>
<output message="ns3:selectRowsetResponse"/>
</operation>
<operation name="countRowset">
<input message="ns3:countRowsetRequest"/>
<output message="ns3:countRowsetResponse"/>
</operation>
<operation name="getTableByTitle">
<input message="ns3:getTableByTitleRequest"/>
<output message="ns3:getTableByTitleResponse"/>
</operation>
<operation name="describeColumns">
<input message="ns3:describeColumnsRequest"/>
<output message="ns3:describeColumnsResponse"/>
</operation>
<operation name="getColumnLookup">
<input message="ns3:getColumnLookupRequest"/>
<output message="ns3:getColumnLookupResponse"/>
</operation>
</portType>
<binding name="servicePortBinding" type="ns3:servicePortType">
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="insertRowset">
<soap:operation soapAction=""/>
<input>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</input>
<output>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</output>
</operation>
<operation name="updateRowset">
<soap:operation soapAction=""/>
<input>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</input>
17
<output>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</output>
</operation>
<operation name="deleteRowset">
<soap:operation soapAction=""/>
<input>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</input>
<output>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</output>
</operation>
<operation name="selectRowset">
<soap:operation soapAction=""/>
<input>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</input>
<output>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</output>
</operation>
<operation name="countRowset">
<soap:operation soapAction=""/>
<input>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</input>
<output>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</output>
</operation>
<operation name="getTableByTitle">
<soap:operation soapAction=""/>
<input>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</input>
<output>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</output>
</operation>
<operation name="describeColumns">
<soap:operation soapAction=""/>
<input>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</input>
<output>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</output>
</operation>
<operation name="getColumnLookup">
<soap:operation soapAction=""/>
<input>
18
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</input>
<output>
<soap:body use="encoded"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="http://mfisoft.ru/soap"/>
</output>
</operation>
</binding>
<service name="Service">
<port name="ServicePortType" binding="ns3:servicePortBinding">
<soap:address location=":SERVICE_URL"/>
</port>
</service>
</definitions>
19