Серверный HTTP интерфейс — различия между версиями

Материал из Oktell
Перейти к: навигация, поиск
(Новая страница: «Наверх Серверная служба осуществляет прослушивание порта 4055 (может быть...»)
 
 
(не показаны 23 промежуточные версии 2 участников)
Строка 2: Строка 2:
  
  
Серверная служба осуществляет прослушивание порта 4055 (может быть изменен в [[Параметры файлов конфигурации#Параметры файла конфигурации серверного приложения|конфигурационном файле]]) и способна исполнять некоторые поступающие на него по протоколу HTTP запросы. Серверная служба осуществляет прослушивание всех сетевых интерфейсов.  
+
Встроенный web-сервер Oktell
 +
* обрабатывает поступающие запросы в рамках Web-API (требуется базовая авторизация под учетной записью любого пользователя, имеющему привилегию исполнения методов Web-API).
 +
* выдает страницы из папки WWW (авторизация не требуется).
 +
* обслуживает подключения WebSocket для работы пользователей в web-клиенте и в решениях, интегрированных с помощью Oktell.js или непосредственно по интеграционному протоколу Oktell WebSocket (авторизация происходит в рамках интеграционного протокола под учетной записью одного из пользователей).
  
Запросы могут поступать с использованием как метода GET, так и POST.  
+
В случае необходимости сервисного доступа к API необходимо создать дополнительную учетную запись пользователя, снабдить его правами и использовать его авторизационную информацию.
  
При необходимости может быть задействована проверка пароля при получении запроса. Для этого в конфигурационном файле серверной службы необходимо указать непустое значение параметру [[Параметры файлов конфигурации#Параметры файла конфигурации серверного приложения|QueryWebServerPassword]]. Все поступающие запросы при этом должны содержать среди параметров <span style="color:green;">password=abc</span>, в противном случае сервер будет отвечать «403 Forbidden».
 
  
 +
Серверная служба осуществляет прослушивание портов 80, 4055 (могут быть изменены в [[Настройки_веб-сервера|настройках веб-сервера]]) и способна исполнять некоторые поступающие на него по протоколу HTTP (или HTTPS) запросы. Серверная служба осуществляет прослушивание всех сетевых интерфейсов.
 +
 +
На все запросы, требующие, но не прошедшие авторизацию, веб-сервер отвечает «403 Forbidden».
 +
В качестве логина/пароля для basic-авторизации выступают логин-пароль любого пользователя, имеющего ролевую привилегию исполнения web-api-запросов.
 +
 +
Запросы могут поступать с использованием методов GET и POST. Как GET, так и POST запрос позволяет перечислять параметры в URL.
 +
 +
Начиная с версии Oktell 2.9 обязательно использование''' basic-авторизации''', например:
 +
http://login:password@192.168.0.1:4055/wp_setuserstate?user=admin&userstateid=5
  
  
Строка 13: Строка 24:
  
  
 +
-------------------------------
  
 
<div id="execsvcscript"></div>
 
<div id="execsvcscript"></div>
Строка 27: Строка 39:
 
* <span style="color:green;">timeout</span> - в случае запуска в синхронном режиме устанавливает максимально допустимое время ожидания завершения сценария в секундах. При превышении обрывает ожидание и возвращает ответ на веб-запрос без результата работы сценария.  
 
* <span style="color:green;">timeout</span> - в случае запуска в синхронном режиме устанавливает максимально допустимое время ожидания завершения сценария в секундах. При превышении обрывает ожидание и возвращает ответ на веб-запрос без результата работы сценария.  
  
http://192.168.0.1:4055/execsvcscript?name=SvcScript1&startparam1=123&startparam2=234&async=0&timeout=10
+
http://login:password@192.168.0.1:4055/execsvcscript?name=SvcScript1&startparam1=123&startparam2=234&async=0&timeout=10
  
 
Пример структуры возвращаемого значения:
 
Пример структуры возвращаемого значения:
Строка 33: Строка 45:
 
<pre>
 
<pre>
 
<?xml version="1.0" encoding="utf-16"?>
 
<?xml version="1.0" encoding="utf-16"?>
 +
<oktellxmlmapper version="80710">
 +
  <data name="result" count="1">
 +
    <property_set name="execsvcscript">
 +
      <property_simple key="started" value="1" name="success" />
 +
      <property_simple key="startresult" value="0" name="success" />
 +
      <property_simple key="returnvalue" name="abcdef" />
 +
    </property_set>
 +
  </data>
 +
</oktellxmlmapper>
 +
</pre>
  
<oktellxmlmapper version="80710">
 
  
  <data name="result" count="1">
+
-------------------------------
  
    <property_set name="execsvcscript">
+
'''execsvcscriptplain'''. Аналогично методу <span style="gray;">execsvcscript</span> осуществляет запуск произвольного служебного сценария на сервере (код запуска 27) с такими же параметрами. Отличие состоит в том, что ответ сценария, сохраненный в переменную «Возвращаемое значение 1» без искажений размещается в контенте ответа на запрос, в то время как базовый метод обрамляет ответ в XML формат.
  
      <property_simple key="started" value="1" name="success" />
+
Служебная переменная «Возвращаемое значение 2» служит для установки HTTP-ответа. По умолчанию 200. Значение "file" позволит вернуть ссылку на файл для скачивания.
  
      <property_simple key="startresult" value="0" name="success" />
+
Служебная переменная «Возвращаемое значение 3» служит для установки дополнительных HTTP-заголовков.
  
      <property_simple key="returnvalue" name="abcdef" />
+
<span style="color:green;">
 +
Для того, чтобы исполнять некоторые служебные сценарии без базовой авторизации можно воспользоваться следующей схемой. Из каталога ''WWW'' файлы отдаются без авторизации. Дополнительные изменения в этом каталоге администратором сервера могут инициировать выдачу ответа не в виде содержимого файла, а в виде результата работы служебного сценария. Разберем на примере, остальное вы сможете сделать по собственным задачам.
  
    </property_set>
+
<span style="color:green;">
 +
1. Положите в папку ''WWW'' в рабочем каталоге сервера файл ''test.html'' с любым тестовым содержимым.
  
  </data>
+
<span style="color:green;">
 +
2. Выполните запрос ''http://server:port/test.html'', подставив адрес и порт доступа к веб-серверу Oktell. Без пароля должно вернуться и отобразиться в браузере содержимое файла.
  
</oktellxmlmapper>
+
<span style="color:green;">
 +
3. Рядом с файлом ''test.html'' создайте файл ''test.html.execsvcscriptplain'', в его тело разместите JSON-форматированную строку, например:
 +
<pre>
 +
{
 +
  "scriptname":"myscript",
 +
  "timeout":10,
 +
  "parameter1":"ЧЕРЕЗ WWW"
 +
}
 
</pre>
 
</pre>
  
 +
<span style="color:green;">
 +
4. Создайте служебный сценарий ''myscript'', выводящий какое-нибудь уведомление, чтобы было видно и понятно, что сценарий запустился.
  
'''execsvcscriptplain'''. Аналогично методу <span style="gray;">execsvcscript</span> осуществляет запуск произвольного служебного сценария на сервере (код запуска 27) с такими же параметрами. Отличие состоит в том, что ответ сценария, сохраненный в переменную «Выходное значение» без искажений размещается в контенте ответа на запрос, в то время как базовый метод обрамляет ответ в XML формат.
+
<span style="color:green;">
 +
5. Выполните тот же запрос ''http://server:port/test.html'' — уведомление должно отобразиться.
  
 +
<span style="color:green;">
 +
6. Все параметры GET запроса (или POST запроса с ''Content-type: application/x-www-form-urlencoded'') будут разобраны и переданы на старт сценария точно также, как если бы исполнялся метод ''execsvcscriptplain''. То есть значения параметров, условия исполнения — асинхр/синхр, таймаут ожидания и.т.д.
  
'''tst_getintnumberreadyusers'''. Для указанного внутреннего стандартного номера возвращает количество свободных и занятых пользователей, а также список свободных пользователей, указанных в виде прямых внутренних стандартных номеров, по которым их можно вызвать.
+
<span style="color:green;">
 +
7. В качестве значения служебной переменной ''Выходное значение'' сценария вы можете организовать вывод любого содержимого, в том числе и HTML страницы, которое будет без изменений возвращено в теле HTTP-ответа.
  
Параметры:  
+
<span style="color:green;">
 +
8. Для передачи в сценарий некоторых служебных данных из тела HTTP-запроса существуют специальные значения, которые можно принудительно назначить в качестве значений одного из пяти возможных стартовых параметров служебного сценария (оригинальные значения, передаваемые в сценарий с помощью параметров GET будут в этом случае частично или полностью перезатерты):
 +
%parameters% — строка параметров GET в неразобранном виде;
 +
%content% — контент запроса;
 +
%headers% — все заголовки HTTP запроса (фактически полный текст запроса без контента);
 +
%page% — адрес запрошенной страницы;
 +
%requestline% — полный текст строки-запроса;
 +
Например:
  
* <span style="color:green;">number</span> - номер, состояние объектов которого необходимо определить.
+
<pre>
 +
{
 +
  "scriptname":"myscript",
 +
  "timeout":10,
 +
  "parameter1":"Константа",
 +
  "parameter3":"%page%"
 +
}
 +
</pre>
  
http://192.168.0.1:4055/tst_getintnumberreadyusers?number=120
+
<span style="color:green;">
 +
При этом значения параметров 2, 4 и 5 будут переданы из самого GET запроса, если они в нем указаны.
 +
</span>
  
Пример структуры возвращаемого значения:
 
  
<pre>
 
<?xml version="1.0" encoding="utf-8"?>
 
  
  <group name="120" ready="2" busy="3">
+
-------------------------------
  
    <element name="223"/>
+
'''execpluginmethod'''. Исполняет указанный метод в [[Встраиваемые_plugin-модули|серверном плагине]], передавая в него параметры и возвращая результат с выходными параметрами.
  
    <element name="227"/>
+
Параметры:
  
  </group>
+
* <span style="color:green;">idmodule</span> - идентификатор серверного плагина.
 +
* <span style="color:green;">idform</span> - идентификатор исполняемого метода (формы).
 +
* <span style="color:green;">inputparams</span> - набор входных значений в JSON строке, соответствующих заявленным входным параметром выбранной формы.
 +
* <span style="color:green;">inputparamsb64</span> - альтернативный вариант кодирования набора входных значений - через base64.
 +
 
 +
<pre>
 +
{
 +
  "param1": "...",
 +
  "param2": "...",
 +
  ...
 +
}
 
</pre>
 
</pre>
  
 +
В ответе возвращается строка с JSON содержимым результата.
  
'''tst_getuserstate'''. Возвращает XML-структуру, содержащую текущее состояние указанного в запросе пользователя.
+
-------------------------------
 +
 
 +
'''tst_getintnumberreadyusers'''. Для указанного внутреннего стандартного номера возвращает количество свободных и занятых пользователей, а также список свободных пользователей, указанных в виде прямых внутренних стандартных номеров, по которым их можно вызвать.
  
 
Параметры:  
 
Параметры:  
Строка 86: Строка 149:
 
* <span style="color:green;">number</span> - номер, состояние объектов которого необходимо определить.  
 
* <span style="color:green;">number</span> - номер, состояние объектов которого необходимо определить.  
  
http://localhost:4055/tst_getuserstate?iduser=DA803F01-EA77-40FA-BC9D-E2EFB36FD5A8
+
http://login:password@192.168.0.1:4055/tst_getintnumberreadyusers?number=120
  
 
Пример структуры возвращаемого значения:
 
Пример структуры возвращаемого значения:
  
<pre>
+
<pre>  
<?xml version="1.0" encoding="utf-16"?>
+
<?xml version="1.0" encoding="utf-8"?>
 +
<group name="120" ready="2" busy="3">
 +
  <element name="223"/>
 +
  <element name="227"/>
 +
</group>
 +
</pre>
  
<oktellxmlmapper version="80710">
 
  
  <data name="userstate" count="1">
+
-------------------------------
  
    <property_set name="user" id="da803f01-ea77-40fa-bc9d-e2efb36fd5a8">
+
'''tst_getuserstate'''. Возвращает XML-структуру, содержащую текущее состояние указанного в запросе пользователя.
  
      <property_simple key="id" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />
+
Параметры:
  
      <property_simple key="state" value="1" name="usReady" />
+
* <span style="color:green;">number</span> - номер, состояние объектов которого необходимо определить.
  
    </property_set>
+
http://login:password@localhost:4055/tst_getuserstate?iduser=DA803F01-EA77-40FA-BC9D-E2EFB36FD5A8
  
  </data>
+
Пример структуры возвращаемого значения:
  
</oktellxmlmapper>
+
<pre>
 +
<?xml version="1.0" encoding="utf-16"?>
 +
<oktellxmlmapper version="80710">
 +
  <data name="userstate" count="1">
 +
    <property_set name="user" id="da803f01-ea77-40fa-bc9d-e2efb36fd5a8">
 +
      <property_simple key="id" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />
 +
      <property_simple key="state" value="1" name="usReady" />
 +
    </property_set>
 +
  </data>
 +
</oktellxmlmapper>
 
</pre>
 
</pre>
  
 +
 +
-------------------------------
  
 
'''getlicensefulltext'''. Возвращает полный текст информации о лицензии на текущем установленном на сервере языке, аналогичный отображаемому в разделе [[Информация о лицензиях|Администрирование. Общие настройки. Информация о лицензии]].
 
'''getlicensefulltext'''. Возвращает полный текст информации о лицензии на текущем установленном на сервере языке, аналогичный отображаемому в разделе [[Информация о лицензиях|Администрирование. Общие настройки. Информация о лицензии]].
  
http://192.168.0.1:4055/getlicensefulltext
+
http://login:password@192.168.0.1:4055/getlicensefulltext
  
  
 
'''getlicensefullxml'''. Возвращает xml-структуру лицензионного сертификата.
 
'''getlicensefullxml'''. Возвращает xml-структуру лицензионного сертификата.
  
http://192.168.0.1:4055/getlicensefullxml
+
http://login:password@192.168.0.1:4055/getlicensefullxml
  
 +
 +
-------------------------------
  
 
'''getlicenseinfo'''. Возвращает значение указанного параметра лицензионного сертификата.
 
'''getlicenseinfo'''. Возвращает значение указанного параметра лицензионного сертификата.
Строка 132: Строка 212:
 
::updatelimitdate - конечная дата поддерживаемых версий согласно лицензии на обновления в формате dd.MM.yyyy.
 
::updatelimitdate - конечная дата поддерживаемых версий согласно лицензии на обновления в формате dd.MM.yyyy.
  
http://192.168.0.1:4055/getlicensefullxml?detail=regserial
+
http://login:password@192.168.0.1:4055/getlicensefullxml?detail=regserial
 +
 
  
 +
-------------------------------
  
 +
<div id="download"></div>
 
'''download'''. Позволяет скачать файл с сервера.
 
'''download'''. Позволяет скачать файл с сервера.
  
::* download/rec/ABC, download/fax/ABC - предоставляет файлы записей разговоров и файлы полученных факсимильных сообщений. Правильная ссылка предоставляется через web-socket подключение.
+
::* download/rec/ABC, download/fax/ABC, download/vm/id - предоставляет файлы записей разговоров, файлы полученных факсимильных сообщений, файлы голосовой почты. Правильная ссылка предоставляется через web-socket подключение. В качестве дополнительного может использоваться параметр ''attachment''.
  
::* download/byscript - предоставляет доступ к произвольному файлу, путь к которому определяется служебным сценарием, запускаемым этим запросом. Все параметры для [[#execsvcscript|execsvcscript]]. Считается что сценарий вернет путь к файлу, который и будет возвращен.
+
::* download/byscript - предоставляет доступ к произвольному файлу, путь к которому определяется служебным сценарием, запускаемым этим запросом. Используются все параметры для метода [[#execsvcscript|execsvcscript]], а также дополнительный параметр ''attachment''. Считается что сценарий вернет путь к файлу, который и будет возвращен.
  
http://192.168.0.1:4055/download/byscript?name=SvcScript1&startparam1=123&startparam2=234&async=0&timeout=10
+
::* download/files - предоставляет доступ к произвольному файлу по прямой ссылке, определяемой параметром path. Путь может быть абсолютным или относительным (относительно рабочего каталога службы сервера Oktell или относительно хранилища файлов). Дополнительно может использоваться параметр ''attachment''. Следует иметь в виду, что в соответствии со значением ключа [[Параметры файлов конфигурации#AllowDownloadFilesDirectlyOnlyFromTemp]] в конфигурационном файле по умолчанию, разрешенная зона для произвольного скачивания ограничена временной папкой и [[Настройки веб-сервера#LocalStoragePath|папкой хранилища]].
  
 +
Параметры:
  
 +
* <span style="color:green;">attachment</span> - «1» указывает на скачивание в виде вложения, «0» - на скачивание в виде медиа (по расширению файла). По умолчанию 1.
 +
 +
http://login:password@192.168.0.1:4055/download/byscript?name=SvcScript1&startparam1=123&startparam2=234&async=0&timeout=10
 +
 +
 +
-------------------------------
 +
 +
<div id="getsharedfile"></div>
 +
'''getsharedfile'''. Позволяет скачать файл из открытой папки локального хранилища (\LocalStorage\Shared) по прямой ссылке без прохождения авторизации при подключении к HTTP серверу. В качестве указания файла может быть передан абсолютный путь на сервере, путь относительно рабочего каталога службы Oktell, путь относительно локального хранилища, а также путь относительно открытой папки локального хранилища. Чуть что не так - возвращает ''404 Not Found''.
 +
 +
Для скачивания файлов, размещенных вне открытой папки локального хранилища, требуется авторизация (если иное не установлено в [[Настройки веб-сервера|настройках HTTP сервера]]) и использование метода '''download/files'''.
 +
 +
Параметры:
 +
 +
* <span style="color:green;">path</span> - Путь относительный или абсолютный к файлу, расположенному в открытом разделе хранилища.
 +
 +
* <span style="color:green;">attachment</span> - «1» указывает на скачивание в виде вложения, «0» - на скачивание в виде медиа (по расширению файла). По умолчанию 1.
 +
 +
http://login:password@192.168.0.1:4055/getsharedfile?path=123.jpg
 +
 +
 +
-------------------------------
 +
 +
<div id="downloadrecordbylink"></div>
 
'''downloadrecordbylink'''. Позволяет скачать файл записи разговора с сервера, код которого упакован и передан через web-socket подключение.
 
'''downloadrecordbylink'''. Позволяет скачать файл записи разговора с сервера, код которого упакован и передан через web-socket подключение.
  
Строка 150: Строка 258:
 
* <span style="color:green;">recordlink</span> - требуемый параметр.
 
* <span style="color:green;">recordlink</span> - требуемый параметр.
  
http://192.168.0.1:4055/downloadrecordbylink?recordlink=ABCDEFGH
+
http://login:password@192.168.0.1:4055/downloadrecordbylink?recordlink=ABCDEFGH
  
  
'''upload'''. Позволяет закачать файл на сервер. Веб-сервер понимает <span style="color:gray;">Content-Type</span> multipart/form-data и application/octet-stream. В запросе должны также присутствовать поля <span style="color:gray;">Content-Transfer-Encoding</span> , <span style="color:gray;">Content-Disposition</span>. В одном запросе с помощью MIME могут быть переданы несколько файлов. Размещение их осуществляется в каталоге <span style="color:gray;">\OktellWorkDirectory\Temp\UploadData</span>. Для формирования неслучайных имен, исходные имена должны быть указаны в качестве параметра суб-заголовка <span style="color:gray;">Content-Disposition</span>.
+
-------------------------------
 +
 
 +
<div id="upload"></div>
 +
'''upload'''. Позволяет закачать файл на сервер. Веб-сервер понимает <span style="color:gray;">Content-Type</span> ''multipart/form-data'' и ''application/octet-stream''. В запросе должны также присутствовать поля <span style="color:gray;">Content-Transfer-Encoding</span>, <span style="color:gray;">Content-Disposition</span>. В одном запросе с помощью MIME могут быть переданы несколько файлов. Для формирования неслучайных имен, исходные имена должны быть указаны в качестве параметра суб-заголовка <span style="color:gray;">Content-Disposition</span>.
 +
Размещение их осуществляется по умолчанию во временном каталоге <span style="color:gray;">\OktellWorkDirectory\Temp\UploadData</span>, если иное не указано с помощью параметров ''storagemode'' и ''subfolder''.
 +
 
 +
Параметры могут быть переданы в URL:
 +
 
 +
* <span style="color:green;">storagemode</span> - Место размещения файла. Варианты значений:
 +
:* ''storage'' - в специально отведенном файловом хранилище, доступном извне только после авторизации, по временному паролю или в случае если авторизация HTTP веб-сервера не используется.
 +
:* ''storageshared'' - в специально отведенном файловом хранилище, открытом для доступа извне без авторизации (если внешний пользователь знает прямую ссылку) с помощью метода '''getsharedfile'''.
 +
:* ''temp'' (по умолчанию) - во временной папке. Гарантировано очищается при перезапуске службы. Файлы доступны для скачивания извне без авторизации по прямой ссылке с помощью метода '''getsharedfile'''.
 +
:* ''script'' - размещается во временной папке, а затем запускается указанный в дополнительных параметрах служебный сценарий, в который в качестве пятого параметра передается результат сохранения файлов с указанием полных путей (xml). Ожидается, что сценарий самостоятельно разместит эти файлы (перенесет в другое место из временной папки). На выход в этом случае возвращается результат, аналогичный результату метода '''execsvcscript'''. Дополнительные параметры также соответствуют параметрам метода '''execsvcscript'''.
 +
:* ''scriptplain'' - размещается во временной папке, а затем запускается указанный в дополнительных параметрах служебный сценарий, в который в качестве пятого параметра передается результат сохранения файлов с указанием полных путей (xml). Ожидается, что сценарий самостоятельно разместит эти файлы (перенесет в другое место из временной папки). На выход в этом случае возвращается результат, аналогичный результату метода '''execsvcscriptplain'''. Дополнительные параметры также соответствуют параметрам метода '''execsvcscriptplain'''.
 +
 
 +
* <span style="color:green;">pathmode</span> - Определяет, абсолютный или относительный путь к сохраненным файлам возвращать в ответе (или передавать в сценарий). Варианты значений: ''absolute'' и ''relative'' соответственно, по умолчанию возвращается относительный путь.
 +
 
 +
* <span style="color:green;">subfolder</span> - Определяет подкаталог (или подпуть), куда разместить закачиваемые файлы, относительно базового определенного хранилища.
 +
 
 +
При размещении файлов необходимо предусмотреть, каким образом и для чего они будут использоваться, кем и при каких условиях скачиваться, надолго или не надолго попадать в хранилище. Обратите внимание на настройку конфигурационного файла [[Параметры файлов конфигурации#AllowDownloadFilesDirectlyOnlyFromTemp|AllowDownloadFilesDirectlyOnlyFromTemp]], а также на параметр ''[[Настройки веб-сервера#LocalStoragePath|Путь к хранилищу файлов]]'' в общих настройках.
 +
 
 +
Запрос должен использовать метод POST с передачей тела сообщения. Сама страница может выглядеть, например, одним из вариантов:
 +
 
 +
http://login:password@192.168.0.1:4055/upload
 +
 
 +
http://login:password@192.168.0.1:4055/upload?storagemode=storage&pathmode=absolute&subfolder=MessageFiles
 +
 
 +
http://login:password@192.168.0.1:4055/upload?storagemode=scriptplain&name=Размещение
  
 
Для примера запроса можно обратиться к сценарию закачки файла на сервер Oktell ([[Файл:uploadfile.oscr]]), присутствующему также в шаблонных сценариях дистрибутива версии начиная с 25.03.2012.  
 
Для примера запроса можно обратиться к сценарию закачки файла на сервер Oktell ([[Файл:uploadfile.oscr]]), присутствующему также в шаблонных сценариях дистрибутива версии начиная с 25.03.2012.  
Строка 162: Строка 297:
  
 
<pre>
 
<pre>
<?xml version="1.0" encoding="utf-16"?>
+
<?xml version="1.0" encoding="utf-16"?>
 +
<uploadfilesresult count="3">
 +
  <file name="1.jpg" saved="1" size="13277" path="C:\Oktell\Temp\UploadData\1.jpg"/>
 +
  <file name="note.txt" saved="1" size="938" path="C:\Oktell\Temp\UploadData\note.txt"/>
 +
  <file name="noteerror.txt" saved="0"/>
 +
</uploadfilesresult>
 +
</pre>
  
<uploadfilesresult count="3">
 
  
  <file name="1.jpg" saved="1" size="13277" path="C:\Oktell\Temp\UploadData\1.jpg"/>
+
-------------------------------
  
  <file name="note.txt" saved="1" size="938" path="C:\Oktell\Temp\UploadData\note.txt"/>
+
<div id="getavatar"></div>
 +
'''getavatar'''. Возвращает изображение(аватарку) указанного пользователя Oktell.
 +
Изображения размещаются в хранилище файлов, и скачивать их можно даже не проходя положенную авторизацию при соединении с HTTP-сервером.
 +
Изображения пользователей хранятся в размере 352х288 (максимальные размеры с учетом пропорций), а также 32x32 и 96x96-ных образах. Ссылки на скачивание выдаются через web-socket подключение, но могут быть сгенерированы и автоматически.
  
  <file name="noteerror.txt" saved="0"/>
+
Параметры могут быть переданы в URL:
  
</uploadfilesresult>
+
* <span style="color:green;">path</span> - путь/имя файла запрашиваемого изображения (если требуется уменьшенная копия, или если известна ссылка или название файла).
 +
 
 +
* <span style="color:green;">userid</span> - если параметр path не указан или некорректен, можно получить полное изображение по идентификатору пользователя.
 +
 
 +
* <span style="color:green;">attachment</span> - «1» указывает на скачивание в виде вложения, «0» - на скачивание в виде медиа-изображения (content-type=image/*). По умолчанию 1.
 +
 
 +
 
 +
-------------------------------
 +
 
 +
<div id="getversion"></div>
 +
'''getversion'''. Возвращает версию сервера Oktell.
 +
 
 +
http://login:password@192.168.0.1:4055/getversion
 +
 
 +
Пример возвращаемого значения:
 +
 
 +
<pre>
 +
<?xml version="1.0" encoding="utf-16"?>
 +
<oktellxmlmapper version="80710">
 +
  <data name="version" count="1">
 +
    <property_set name="version">
 +
      <property_cdata key="text"><![CDATA[Версия программы: 2.7.120918(4644.26860). Версия БД: 120711.]]></property_cdata>
 +
      <property_cdata key="environment"><![CDATA[1.1.4322.2032]]></property_cdata>
 +
      <property_cdata key="build"><![CDATA[2.7.4644.26860]]></property_cdata>
 +
      <property_simple key="date" value="120918" />
 +
      <property_cdata key="halbuild"><![CDATA[2.15.40.134]]></property_cdata>
 +
      <property_simple key="haldate" value="120913" />
 +
    </property_set>
 +
  </data>
 +
</oktellxmlmapper>
 
</pre>
 
</pre>
  
  
 +
-------------------------------
 +
 +
<div id="gettotalqueueinfo"></div>
 +
'''gettotalqueueinfo'''. Возвращает информацию обо всех очередях в настоящее время с описанием внутренних номеров, списка абонентов у каждого из них. Информация возвращается в JSON представлении.
 +
 +
http://login:password@192.168.0.1:4055/gettotalqueueinfo
 +
 +
Пример структуры возвращаемого значения:
 +
<pre>
 +
[
 +
{
 +
  "numid": "5d2965c3-39ce-4929-912e-c97031582fc6",
 +
  "numprefix": "14",
 +
  "ruleid": "bb4c2822-34c8-4bff-9e9b-e2826b904204",
 +
  "rulename": "Петр",
 +
  "queue": [
 +
  {
 +
    "chainid": "dd8466d8-7aa3-4df1-b1b7-b933a11da518",
 +
    "objecttype": 0,
 +
    "objecttypestr": "qotQueueLogic",
 +
    "objectid": "263fb71f-88d2-4787-b16c-e22559336030",
 +
    "queuesource": 2,
 +
    "queuesourcestr": "qsIVR",
 +
    "queuepriority": 10,
 +
    "callerid": "21",
 +
    "calledid": "14",
 +
    "srclineid": "173210d8-fcfc-49f7-b770-d3609445b188",
 +
    "srclinenumber": "17633",
 +
    "srcelementid": "173210d8-fcfc-49f7-b770-d3609445b188"
 +
    "managedlineid": "173210d8-fcfc-49f7-b770-d3609445b188",
 +
    "managedlinenumber": "17633",
 +
    "department": "",
 +
    "isuser": true,
 +
    "userid": "7cf84c23-2736-4fc8-9bf7-bfbb4778fb01",
 +
    "userlogin": "manager2",
 +
    "username": "Виктор Викторыч",
 +
    "istask": false,
 +
    "startqueuetime": "2012-09-28 09:46:33",
 +
    "lenqueue": 41.953125
 +
  }
 +
  ] 
 +
}
 +
]
 +
</pre>
 +
 +
 +
-------------------------------
  
 
Несколько следующих команд предоставляют доступ к функционалу управления звонками, аналогичному доступным для клиентских приложений. Все эти запросы выполняются от имени указанной линии (параметр line), указанного пользователя (параметр user) или указанного рабочего места (параметр wp). Достаточно указания только одного из вышеприведенных параметров. В качестве значения может использоваться guid-идентификатор, название, имя пользователя, логин, номер линии и т.д. По указанному значению однозначно определяется внутренняя линия, от имени которой и исполняется команда.
 
Несколько следующих команд предоставляют доступ к функционалу управления звонками, аналогичному доступным для клиентских приложений. Все эти запросы выполняются от имени указанной линии (параметр line), указанного пользователя (параметр user) или указанного рабочего места (параметр wp). Достаточно указания только одного из вышеприведенных параметров. В качестве значения может использоваться guid-идентификатор, название, имя пользователя, логин, номер линии и т.д. По указанному значению однозначно определяется внутренняя линия, от имени которой и исполняется команда.
Строка 182: Строка 401:
 
'''wp_getchaincontent'''. Возвращает текущий контент цепочки, в которой участвует линия. Результат представляет собой JSON-структуру.
 
'''wp_getchaincontent'''. Возвращает текущий контент цепочки, в которой участвует линия. Результат представляет собой JSON-структуру.
  
http://192.168.0.1:4055/wp_getchaincontent?user=DA803F01-EA77-40FA-BC9D-E2EFB36FD5A8
+
http://login:password@192.168.0.1:4055/wp_getchaincontent?user=DA803F01-EA77-40FA-BC9D-E2EFB36FD5A8
  
 
Пример структуры возвращаемого значения:
 
Пример структуры возвращаемого значения:
 
<pre>
 
<pre>
 
{
 
{
"createtime": "2011-07-27 14:41:28",
+
  "createtime": "2011-07-27 14:41:28",
"trace": [
+
  "chainid": "c7b333a5-93b3-4277-8c60-9844d63a4732"
{
+
  "customfield": "",
"userlogin": "Dima",
+
  "trace": [
"isuser": true,
+
    {
"queuepriority": 10,
+
      "contentelementtype": "call",
"managedlineid": "e76c86ea-a28a-4519-b4ff-8879a92c62b7",
+
      "pbxdirection": "internal",
"contentelementtype": "call",
+
      "objectid": "63d38304-3bff-4e8e-8c42-8f2f11b57c73",
"srclinenumber": "17002",
+
      "objecttype": 0,
"userid": "2a594b51-bb89-4da6-a69f-f48761baf0d9",
+
      "objecttypestr": "qotQueueLogic",
"calledid": "183",
+
      "queuesource": 1,
"istask": false,
+
      "queuesourcestr": "qsLineLogic",
"pbxdirection": "internal",
+
      "queuepriority": 10,
"queuesourcestr": "qsLineLogic",
+
      "istask": false,
"srclineid": "e76c86ea-a28a-4519-b4ff-8879a92c62b7",
+
      "managedlineid": "e76c86ea-a28a-4519-b4ff-8879a92c62b7",
"objecttypestr": "qotQueueLogic",
+
      "isuser": true,
"managedlinenumber": "17002",
+
      "userlogin": "Dima",
"objecttype": 0,
+
      "startqueuetime": "2011-07-27 14:41:29",
"callerid": "#999",
+
      "department": "Программисты",
"queuesource": 1,
+
      "callerid": "#999",
"department": "Программисты",
+
      "calledid": "183",
"startqueuetime": "2011-07-27 14:41:29",
+
      "srcelementid": "e76c86ea-a28a-4519-b4ff-8879a92c62b7",
"objectid": "63d38304-3bff-4e8e-8c42-8f2f11b57c73",
+
      "srclineid": "e76c86ea-a28a-4519-b4ff-8879a92c62b7",
"username": "Дмитрий Евгеньевич",
+
      "srclinenumber": "17002",
"srcelementid": "e76c86ea-a28a-4519-b4ff-8879a92c62b7"
+
      "managedlinenumber": "17002",
},
+
      "userid": "2a594b51-bb89-4da6-a69f-f48761baf0d9",
{
+
      "username": "Дмитрий Евгеньевич"
"contentelementtype": "commutation",
+
    },
"connectiontype": 3,
+
    {
"btext": "Виктор Викторыч",
+
      "contentelementtype": "commutation",
"aisuser": true,
+
      "commutationid": "8fc371f2-ae36-4744-ae7f-bee8c79385a8",
"atext": "Дмитрий Евгеньевич",
+
      "connectiontype": 3,
"connectiontypestr": "ctInnerInner",
+
      "connectiontypestr": "ctInnerInner",
"buserid": "7cf84c23-2736-4fc8-9bf7-bfbb4778fb01",
+
      "alineid": "e76c86ea-a28a-4519-b4ff-8879a92c62b7",
"ausername": "Дмитрий Евгеньевич",
+
      "alinenumber": "17002",
"aoutnumber": "#999",
+
      "aisuser": true,
"blineid": "070aafb0-f47c-4df5-a01f-7bb08ceee269",
+
      "auserid": "2a594b51-bb89-4da6-a69f-f48761baf0d9",
"auserlogin": "Dima",
+
      "auserlogin": "Dima",
"bisuser": true,
+
      "ausername": "Дмитрий Евгеньевич",
"buserlogin": "VIKTIRICH",
+
      "aoutnumber": "#999",
"auserid": "2a594b51-bb89-4da6-a69f-f48761baf0d9",
+
      "anumberdialed": "183",
"busername": "Виктор Викторыч",
+
      "atext": "Дмитрий Евгеньевич",
"timeanswer": "2011-07-27 14:41:31",
+
      "blineid": "070aafb0-f47c-4df5-a01f-7bb08ceee269",
"isrecorded": true,
+
      "blinenumber": "17001",
"commutationid": "8fc371f2-ae36-4744-ae7f-bee8c79385a8",
+
      "bisuser": true,
"bnumberdialed": "",
+
      "buserid": "7cf84c23-2736-4fc8-9bf7-bfbb4778fb01",
"timestart": "2011-07-27 14:41:29",
+
      "buserlogin": "VIKTIRICH",
"boutnumber": "183",
+
      "busername": "Виктор Викторыч",
"anumberdialed": "183",
+
      "boutnumber": "183",
"alinenumber": "17002",
+
      "bnumberdialed": "",
"blinenumber": "17001",
+
      "btext": "Виктор Викторыч",
"alineid": "e76c86ea-a28a-4519-b4ff-8879a92c62b7"
+
      "timestart": "2011-07-27 14:41:29",
}
+
      "timeanswer": "2011-07-27 14:41:31",
],
+
      "isrecorded": true
"customfield": "",
+
    }
"chainid": "c7b333a5-93b3-4277-8c60-9844d63a4732"
+
  ] 
 
}
 
}
 
</pre>
 
</pre>
 +
 +
 +
-------------------------------
  
 
'''wp_getabonentinfo'''. Возвращает информацию о противоположном абоненте в коммутации, в которой участвует линия. Результат представляет собой JSON-структуру
 
'''wp_getabonentinfo'''. Возвращает информацию о противоположном абоненте в коммутации, в которой участвует линия. Результат представляет собой JSON-структуру
  
http://192.168.0.1:4055/wp_getchaincontent?user=ivan
+
http://login:password@192.168.0.1:4055/wp_getchaincontent?user=ivan
  
 
Пример структуры возвращаемого значения:
 
Пример структуры возвращаемого значения:
 
<pre>
 
<pre>
 
{
 
{
"abonentinfo": {
+
  "currentlinestate": 32,
"cansendfiles": false,
+
  "currentlinestatestr": "lsCommutated",
"isconference": false,
+
  "abonentinfo": {
"callerlineid": "070aafb0-f47c-4df5-a01f-7bb08ceee269",
+
    "cansendfiles": false,
"callercomment": "",
+
    "isconference": false,
"isuser": true,
+
    "callerlineid": "070aafb0-f47c-4df5-a01f-7bb08ceee269",
"callername": "Виктор Викторыч",
+
    "callercomment": "",
"canswitchtoconf": false,
+
    "isuser": true,
"callerusername": "Виктор Викторыч",
+
    "callername": "Виктор Викторыч",
"commutationid": "21164dde-0c43-46cf-b00f-77bd51cbe284",
+
    "canswitchtoconf": false,
"calleruserlogin": "VIKTIRICH",
+
    "callerusername": "Виктор Викторыч",
"callerdescription": "",
+
    "commutationid": "21164dde-0c43-46cf-b00f-77bd51cbe284",
"callerlinenum": "17001",
+
    "calleruserlogin": "VIKTIRICH",
"isivr": false,
+
    "callerdescription": "",
"callerid": "183",
+
    "callerlinenum": "17001",
"callersimple": "Виктор Викторыч",
+
    "isivr": false,
"calleruserid": "7cf84c23-2736-4fc8-9bf7-bfbb4778fb01",
+
    "callerid": "183",
"canfax": true,
+
    "callersimple": "Виктор Викторыч",
"canvideo": false,
+
    "calleruserid": "7cf84c23-2736-4fc8-9bf7-bfbb4778fb01",
"chainid": "b8b552d1-7cb9-4469-a45d-451f27516af1",
+
    "canfax": true,
"isextline": false
+
    "canvideo": false,
},
+
    "chainid": "b8b552d1-7cb9-4469-a45d-451f27516af1",
"currentlinestatestr": "lsCommutated",
+
    "isextline": false
"currentlinestate": 32
+
  }
 
}
 
}
 
</pre>
 
</pre>
  
 +
 +
-------------------------------
  
 
'''wp_autocallstart'''. Запускает автодозвон или разовый звонок на указанный номер.
 
'''wp_autocallstart'''. Запускает автодозвон или разовый звонок на указанный номер.
  
Дополнительные параметры:  
+
Дополнительные параметры:
  
 
* <span style="color:green;">number</span> - обязательный параметр.   
 
* <span style="color:green;">number</span> - обязательный параметр.   
Строка 299: Строка 523:
 
::back - сначала осуществляется вызов самой линии, а затем вызов от ее имени указанного номера.  
 
::back - сначала осуществляется вызов самой линии, а затем вызов от ее имени указанного номера.  
  
http://192.168.0.1:4055/wp_autocallstart?line=16038&number=538&direction=pbx
+
http://login:password@192.168.0.1:4055/wp_autocallstart?line=16038&number=538&direction=pbx
  
 +
 +
-------------------------------
  
 
'''wp_switchcall'''. Производит flash-переключение текущего звонка на указанный номер. Если линия неактивна, то запускает автодозвон. Все параметры аналогичны [[#wp_autocallstart|wp_autocallstart]].
 
'''wp_switchcall'''. Производит flash-переключение текущего звонка на указанный номер. Если линия неактивна, то запускает автодозвон. Все параметры аналогичны [[#wp_autocallstart|wp_autocallstart]].
  
 +
 +
-------------------------------
  
 
'''wp_autocallstop'''. Останавливает активную сессию автодозвона.
 
'''wp_autocallstop'''. Останавливает активную сессию автодозвона.
  
http://192.168.0.1:4055/wp_autocallstop?line=16038
+
http://login:password@192.168.0.1:4055/wp_autocallstop?line=16038
 +
 
  
 +
-------------------------------
  
 
'''wp_flash'''. Генерирует flash от имени линии.
 
'''wp_flash'''. Генерирует flash от имени линии.
  
http://192.168.0.1:4055/wp_flash?user=ivan
+
http://login:password@192.168.0.1:4055/wp_flash?user=ivan
  
 +
Дополнительные параметры:
 +
 +
* <span style="color:green;">mode</span> - Режим переключения, если на удержании уже имеется абонент.
 +
:* ''abort'' - отбой текущему, возврат к тому, кто на удержании.
 +
:* ''switch'' - возврат к тому, кто на удержании, текущего на удержание
 +
:* ''next'' - отбой текущему, переход сразу в набор номера, не возвращаясь к тому, кто на удержании.
 +
 +
 +
-------------------------------
  
 
'''wp_declinecall'''. Отклоняет входящий вызов.
 
'''wp_declinecall'''. Отклоняет входящий вызов.
  
http://192.168.0.1:4055/wp_declinecall?wp=OPERATOR1
+
http://login:password@192.168.0.1:4055/wp_declinecall?wp=OPERATOR1
  
 +
 +
-------------------------------
 +
 +
'''wp_answercall'''. Отвечает на входящий вызов.
 +
 +
http://login:password@192.168.0.1:4055/wp_answercall?user=ivan
 +
 +
 +
-------------------------------
 +
 +
'''wp_abortcall'''. Положить трубку. Завершает звонок.
 +
 +
http://login:password@192.168.0.1:4055/wp_abortcall?line=16001
 +
 +
 +
-------------------------------
  
 
'''wp_setuserstate'''. Изменяет текущее состояние пользователя и/или перемещает его из одного режима в другой. В любом случае, если пользователь определен, возвращается ответ 200 OK без дополнительных параметров. Оповещение о смене режимов и состояний протекает в обычном режиме путем событийного оповещения клиентского рабочего места.
 
'''wp_setuserstate'''. Изменяет текущее состояние пользователя и/или перемещает его из одного режима в другой. В любом случае, если пользователь определен, возвращается ответ 200 OK без дополнительных параметров. Оповещение о смене режимов и состояний протекает в обычном режиме путем событийного оповещения клиентского рабочего места.
Строка 333: Строка 588:
  
 
* <span style="color:green;">oncallcenter</span> - 0 или 1, определяет активность режима call-центра. Производит дополнительно смену состояний, если текущее состояние противоречит выбранному режиму (вывод из перерыва при выходе, вывод из переадресации при входе в call-центр).
 
* <span style="color:green;">oncallcenter</span> - 0 или 1, определяет активность режима call-центра. Производит дополнительно смену состояний, если текущее состояние противоречит выбранному режиму (вывод из перерыва при выходе, вывод из переадресации при входе в call-центр).
 +
 +
* <span style="color:green;">onccmanual</span> - 0 или 1, определяет активность ручного режима в call-центре. Может быть изменено только при нахождении пользователя в call-центре.
  
 
* <span style="color:green;">onlunch</span> - 0 или 1, определяет активность режима перерыва. Доступно только при включенном режиме call-центра. Может выставляться как отдельно, так и одновременно с определением других режимов состояния. При активном режиме перерыва пользователь переводится в состояние перерыва вместо готовности всякий раз, как только освобождается. Вместе с переводом в режим перерыва возможно указание причины и кода причины перерыва (параметры lunchreasonid и lunchreasonmsg) - для регламентированных причин, содержащихся в БД указывается только код, для индивидуальных причин указывается только текст.
 
* <span style="color:green;">onlunch</span> - 0 или 1, определяет активность режима перерыва. Доступно только при включенном режиме call-центра. Может выставляться как отдельно, так и одновременно с определением других режимов состояния. При активном режиме перерыва пользователь переводится в состояние перерыва вместо готовности всякий раз, как только освобождается. Вместе с переводом в режим перерыва возможно указание причины и кода причины перерыва (параметры lunchreasonid и lunchreasonmsg) - для регламентированных причин, содержащихся в БД указывается только код, для индивидуальных причин указывается только текст.
Строка 340: Строка 597:
 
* <span style="color:green;">lunchreasonmsg</span> - описание индивидуальной причины перерыва.  
 
* <span style="color:green;">lunchreasonmsg</span> - описание индивидуальной причины перерыва.  
  
http://192.168.0.1:4055/wp_setuserstate?user=ivanov&userstateid=5
+
http://login:password@192.168.0.1:4055/wp_setuserstate?user=ivanov&userstateid=5
 +
 
 +
http://login:password@192.168.0.1:4055/wp_setuserstate?user=ivanov&onlunch=1&lunchreasonid=1001
 +
 
  
http://192.168.0.1:4055/wp_setuserstate?user=ivanov&onlunch=1&lunchreasonid=1001
+
-------------------------------

Текущая версия на 14:53, 12 октября 2017

Наверх


Встроенный web-сервер Oktell

  • обрабатывает поступающие запросы в рамках Web-API (требуется базовая авторизация под учетной записью любого пользователя, имеющему привилегию исполнения методов Web-API).
  • выдает страницы из папки WWW (авторизация не требуется).
  • обслуживает подключения WebSocket для работы пользователей в web-клиенте и в решениях, интегрированных с помощью Oktell.js или непосредственно по интеграционному протоколу Oktell WebSocket (авторизация происходит в рамках интеграционного протокола под учетной записью одного из пользователей).

В случае необходимости сервисного доступа к API необходимо создать дополнительную учетную запись пользователя, снабдить его правами и использовать его авторизационную информацию.


Серверная служба осуществляет прослушивание портов 80, 4055 (могут быть изменены в настройках веб-сервера) и способна исполнять некоторые поступающие на него по протоколу HTTP (или HTTPS) запросы. Серверная служба осуществляет прослушивание всех сетевых интерфейсов.

На все запросы, требующие, но не прошедшие авторизацию, веб-сервер отвечает «403 Forbidden». В качестве логина/пароля для basic-авторизации выступают логин-пароль любого пользователя, имеющего ролевую привилегию исполнения web-api-запросов.

Запросы могут поступать с использованием методов GET и POST. Как GET, так и POST запрос позволяет перечислять параметры в URL.

Начиная с версии Oktell 2.9 обязательно использование basic-авторизации, например:

http://login:password@192.168.0.1:4055/wp_setuserstate?user=admin&userstateid=5


Команды серверного веб-интерфейса


execsvcscript. Осуществляет запуск произвольного служебного сценария на сервере (код запуска 27). Запуск служебного сценария может осуществляться синхронно и асинхронно. В синхронном режиме возвращаемое сценарием значение (присвоенное служебной переменной Возвращаемое значение 1) передается в качестве ответа на запрос.

Параметры:

  • name - название служебного сценария, подлежащего запуску, существующего и размещенного на сервере в каталоге общих сценариев.
  • startparam1, startparam2, startparam3, startparam4, startparam5 - значения стартовых параметров, передаваемых в сценарий и доступных в качестве соответствующих функций.
  • async - режим запуска служебного сценария. 0 - синхронно с ожиданием завершения и возвратом значения, 1 - асинхронно.
  • timeout - в случае запуска в синхронном режиме устанавливает максимально допустимое время ожидания завершения сценария в секундах. При превышении обрывает ожидание и возвращает ответ на веб-запрос без результата работы сценария.

http://login:password@192.168.0.1:4055/execsvcscript?name=SvcScript1&startparam1=123&startparam2=234&async=0&timeout=10

Пример структуры возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>
<oktellxmlmapper version="80710">
  <data name="result" count="1">
    <property_set name="execsvcscript">
      <property_simple key="started" value="1" name="success" />
      <property_simple key="startresult" value="0" name="success" />
      <property_simple key="returnvalue" name="abcdef" />
    </property_set>
  </data>
</oktellxmlmapper>



execsvcscriptplain. Аналогично методу execsvcscript осуществляет запуск произвольного служебного сценария на сервере (код запуска 27) с такими же параметрами. Отличие состоит в том, что ответ сценария, сохраненный в переменную «Возвращаемое значение 1» без искажений размещается в контенте ответа на запрос, в то время как базовый метод обрамляет ответ в XML формат.

Служебная переменная «Возвращаемое значение 2» служит для установки HTTP-ответа. По умолчанию 200. Значение "file" позволит вернуть ссылку на файл для скачивания.

Служебная переменная «Возвращаемое значение 3» служит для установки дополнительных HTTP-заголовков.

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

1. Положите в папку WWW в рабочем каталоге сервера файл test.html с любым тестовым содержимым.

2. Выполните запрос http://server:port/test.html, подставив адрес и порт доступа к веб-серверу Oktell. Без пароля должно вернуться и отобразиться в браузере содержимое файла.

3. Рядом с файлом test.html создайте файл test.html.execsvcscriptplain, в его тело разместите JSON-форматированную строку, например:

{
  "scriptname":"myscript", 
  "timeout":10, 
  "parameter1":"ЧЕРЕЗ WWW"
}

4. Создайте служебный сценарий myscript, выводящий какое-нибудь уведомление, чтобы было видно и понятно, что сценарий запустился.

5. Выполните тот же запрос http://server:port/test.html — уведомление должно отобразиться.

6. Все параметры GET запроса (или POST запроса с Content-type: application/x-www-form-urlencoded) будут разобраны и переданы на старт сценария точно также, как если бы исполнялся метод execsvcscriptplain. То есть значения параметров, условия исполнения — асинхр/синхр, таймаут ожидания и.т.д.

7. В качестве значения служебной переменной Выходное значение сценария вы можете организовать вывод любого содержимого, в том числе и HTML страницы, которое будет без изменений возвращено в теле HTTP-ответа.

8. Для передачи в сценарий некоторых служебных данных из тела HTTP-запроса существуют специальные значения, которые можно принудительно назначить в качестве значений одного из пяти возможных стартовых параметров служебного сценария (оригинальные значения, передаваемые в сценарий с помощью параметров GET будут в этом случае частично или полностью перезатерты): %parameters% — строка параметров GET в неразобранном виде; %content% — контент запроса; %headers% — все заголовки HTTP запроса (фактически полный текст запроса без контента); %page% — адрес запрошенной страницы; %requestline% — полный текст строки-запроса; Например:

{
  "scriptname":"myscript", 
  "timeout":10, 
  "parameter1":"Константа",
  "parameter3":"%page%"
}

При этом значения параметров 2, 4 и 5 будут переданы из самого GET запроса, если они в нем указаны.



execpluginmethod. Исполняет указанный метод в серверном плагине, передавая в него параметры и возвращая результат с выходными параметрами.

Параметры:

  • idmodule - идентификатор серверного плагина.
  • idform - идентификатор исполняемого метода (формы).
  • inputparams - набор входных значений в JSON строке, соответствующих заявленным входным параметром выбранной формы.
  • inputparamsb64 - альтернативный вариант кодирования набора входных значений - через base64.
{
  "param1": "...",
  "param2": "...",
  ...
}

В ответе возвращается строка с JSON содержимым результата.


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

Параметры:

  • number - номер, состояние объектов которого необходимо определить.

http://login:password@192.168.0.1:4055/tst_getintnumberreadyusers?number=120

Пример структуры возвращаемого значения:

 
<?xml version="1.0" encoding="utf-8"?>
<group name="120" ready="2" busy="3">
  <element name="223"/>
  <element name="227"/>
</group>



tst_getuserstate. Возвращает XML-структуру, содержащую текущее состояние указанного в запросе пользователя.

Параметры:

  • number - номер, состояние объектов которого необходимо определить.

http://login:password@localhost:4055/tst_getuserstate?iduser=DA803F01-EA77-40FA-BC9D-E2EFB36FD5A8

Пример структуры возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>
<oktellxmlmapper version="80710">
  <data name="userstate" count="1">
    <property_set name="user" id="da803f01-ea77-40fa-bc9d-e2efb36fd5a8">
      <property_simple key="id" value="da803f01-ea77-40fa-bc9d-e2efb36fd5a8" />
      <property_simple key="state" value="1" name="usReady" />
    </property_set>
  </data>
</oktellxmlmapper>



getlicensefulltext. Возвращает полный текст информации о лицензии на текущем установленном на сервере языке, аналогичный отображаемому в разделе Администрирование. Общие настройки. Информация о лицензии.

http://login:password@192.168.0.1:4055/getlicensefulltext


getlicensefullxml. Возвращает xml-структуру лицензионного сертификата.

http://login:password@192.168.0.1:4055/getlicensefullxml



getlicenseinfo. Возвращает значение указанного параметра лицензионного сертификата.

Параметры:

  • detail - требуемый параметр.
regserial - 7-значный номер регистрации,
confirmdate - дата следующего подтверждения сертификата в формате dd.MM.yyyy,
updatelimitdate - конечная дата поддерживаемых версий согласно лицензии на обновления в формате dd.MM.yyyy.

http://login:password@192.168.0.1:4055/getlicensefullxml?detail=regserial



download. Позволяет скачать файл с сервера.

  • download/rec/ABC, download/fax/ABC, download/vm/id - предоставляет файлы записей разговоров, файлы полученных факсимильных сообщений, файлы голосовой почты. Правильная ссылка предоставляется через web-socket подключение. В качестве дополнительного может использоваться параметр attachment.
  • download/byscript - предоставляет доступ к произвольному файлу, путь к которому определяется служебным сценарием, запускаемым этим запросом. Используются все параметры для метода execsvcscript, а также дополнительный параметр attachment. Считается что сценарий вернет путь к файлу, который и будет возвращен.
  • download/files - предоставляет доступ к произвольному файлу по прямой ссылке, определяемой параметром path. Путь может быть абсолютным или относительным (относительно рабочего каталога службы сервера Oktell или относительно хранилища файлов). Дополнительно может использоваться параметр attachment. Следует иметь в виду, что в соответствии со значением ключа Параметры файлов конфигурации#AllowDownloadFilesDirectlyOnlyFromTemp в конфигурационном файле по умолчанию, разрешенная зона для произвольного скачивания ограничена временной папкой и папкой хранилища.

Параметры:

  • attachment - «1» указывает на скачивание в виде вложения, «0» - на скачивание в виде медиа (по расширению файла). По умолчанию 1.

http://login:password@192.168.0.1:4055/download/byscript?name=SvcScript1&startparam1=123&startparam2=234&async=0&timeout=10



getsharedfile. Позволяет скачать файл из открытой папки локального хранилища (\LocalStorage\Shared) по прямой ссылке без прохождения авторизации при подключении к HTTP серверу. В качестве указания файла может быть передан абсолютный путь на сервере, путь относительно рабочего каталога службы Oktell, путь относительно локального хранилища, а также путь относительно открытой папки локального хранилища. Чуть что не так - возвращает 404 Not Found.

Для скачивания файлов, размещенных вне открытой папки локального хранилища, требуется авторизация (если иное не установлено в настройках HTTP сервера) и использование метода download/files.

Параметры:

  • path - Путь относительный или абсолютный к файлу, расположенному в открытом разделе хранилища.
  • attachment - «1» указывает на скачивание в виде вложения, «0» - на скачивание в виде медиа (по расширению файла). По умолчанию 1.

http://login:password@192.168.0.1:4055/getsharedfile?path=123.jpg



downloadrecordbylink. Позволяет скачать файл записи разговора с сервера, код которого упакован и передан через web-socket подключение.

Параметры:

  • recordlink - требуемый параметр.

http://login:password@192.168.0.1:4055/downloadrecordbylink?recordlink=ABCDEFGH



upload. Позволяет закачать файл на сервер. Веб-сервер понимает Content-Type multipart/form-data и application/octet-stream. В запросе должны также присутствовать поля Content-Transfer-Encoding, Content-Disposition. В одном запросе с помощью MIME могут быть переданы несколько файлов. Для формирования неслучайных имен, исходные имена должны быть указаны в качестве параметра суб-заголовка Content-Disposition. Размещение их осуществляется по умолчанию во временном каталоге \OktellWorkDirectory\Temp\UploadData, если иное не указано с помощью параметров storagemode и subfolder.

Параметры могут быть переданы в URL:

  • storagemode - Место размещения файла. Варианты значений:
  • storage - в специально отведенном файловом хранилище, доступном извне только после авторизации, по временному паролю или в случае если авторизация HTTP веб-сервера не используется.
  • storageshared - в специально отведенном файловом хранилище, открытом для доступа извне без авторизации (если внешний пользователь знает прямую ссылку) с помощью метода getsharedfile.
  • temp (по умолчанию) - во временной папке. Гарантировано очищается при перезапуске службы. Файлы доступны для скачивания извне без авторизации по прямой ссылке с помощью метода getsharedfile.
  • script - размещается во временной папке, а затем запускается указанный в дополнительных параметрах служебный сценарий, в который в качестве пятого параметра передается результат сохранения файлов с указанием полных путей (xml). Ожидается, что сценарий самостоятельно разместит эти файлы (перенесет в другое место из временной папки). На выход в этом случае возвращается результат, аналогичный результату метода execsvcscript. Дополнительные параметры также соответствуют параметрам метода execsvcscript.
  • scriptplain - размещается во временной папке, а затем запускается указанный в дополнительных параметрах служебный сценарий, в который в качестве пятого параметра передается результат сохранения файлов с указанием полных путей (xml). Ожидается, что сценарий самостоятельно разместит эти файлы (перенесет в другое место из временной папки). На выход в этом случае возвращается результат, аналогичный результату метода execsvcscriptplain. Дополнительные параметры также соответствуют параметрам метода execsvcscriptplain.
  • pathmode - Определяет, абсолютный или относительный путь к сохраненным файлам возвращать в ответе (или передавать в сценарий). Варианты значений: absolute и relative соответственно, по умолчанию возвращается относительный путь.
  • subfolder - Определяет подкаталог (или подпуть), куда разместить закачиваемые файлы, относительно базового определенного хранилища.

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

Запрос должен использовать метод POST с передачей тела сообщения. Сама страница может выглядеть, например, одним из вариантов:

http://login:password@192.168.0.1:4055/upload

http://login:password@192.168.0.1:4055/upload?storagemode=storage&pathmode=absolute&subfolder=MessageFiles

http://login:password@192.168.0.1:4055/upload?storagemode=scriptplain&name=Размещение

Для примера запроса можно обратиться к сценарию закачки файла на сервер Oktell (Файл:Uploadfile.oscr), присутствующему также в шаблонных сценариях дистрибутива версии начиная с 25.03.2012.

В качестве ответа возвращается XML-структура с описанием всех сохраненных файлов и путей к ним.

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>
<uploadfilesresult count="3">
  <file name="1.jpg" saved="1" size="13277" path="C:\Oktell\Temp\UploadData\1.jpg"/>
  <file name="note.txt" saved="1" size="938" path="C:\Oktell\Temp\UploadData\note.txt"/>
  <file name="noteerror.txt" saved="0"/>
</uploadfilesresult>



getavatar. Возвращает изображение(аватарку) указанного пользователя Oktell. Изображения размещаются в хранилище файлов, и скачивать их можно даже не проходя положенную авторизацию при соединении с HTTP-сервером. Изображения пользователей хранятся в размере 352х288 (максимальные размеры с учетом пропорций), а также 32x32 и 96x96-ных образах. Ссылки на скачивание выдаются через web-socket подключение, но могут быть сгенерированы и автоматически.

Параметры могут быть переданы в URL:

  • path - путь/имя файла запрашиваемого изображения (если требуется уменьшенная копия, или если известна ссылка или название файла).
  • userid - если параметр path не указан или некорректен, можно получить полное изображение по идентификатору пользователя.
  • attachment - «1» указывает на скачивание в виде вложения, «0» - на скачивание в виде медиа-изображения (content-type=image/*). По умолчанию 1.



getversion. Возвращает версию сервера Oktell.

http://login:password@192.168.0.1:4055/getversion

Пример возвращаемого значения:

<?xml version="1.0" encoding="utf-16"?>
<oktellxmlmapper version="80710">
  <data name="version" count="1">
    <property_set name="version">
      <property_cdata key="text"><![CDATA[Версия программы: 2.7.120918(4644.26860). Версия БД: 120711.]]></property_cdata>
      <property_cdata key="environment"><![CDATA[1.1.4322.2032]]></property_cdata>
      <property_cdata key="build"><![CDATA[2.7.4644.26860]]></property_cdata>
      <property_simple key="date" value="120918" />
      <property_cdata key="halbuild"><![CDATA[2.15.40.134]]></property_cdata>
      <property_simple key="haldate" value="120913" />
    </property_set>
  </data>
</oktellxmlmapper>



gettotalqueueinfo. Возвращает информацию обо всех очередях в настоящее время с описанием внутренних номеров, списка абонентов у каждого из них. Информация возвращается в JSON представлении.

http://login:password@192.168.0.1:4055/gettotalqueueinfo

Пример структуры возвращаемого значения:

[
 {
  "numid": "5d2965c3-39ce-4929-912e-c97031582fc6",
  "numprefix": "14",
  "ruleid": "bb4c2822-34c8-4bff-9e9b-e2826b904204",
  "rulename": "Петр",
  "queue": [
   {
    "chainid": "dd8466d8-7aa3-4df1-b1b7-b933a11da518",
    "objecttype": 0,
    "objecttypestr": "qotQueueLogic",
    "objectid": "263fb71f-88d2-4787-b16c-e22559336030",
    "queuesource": 2,
    "queuesourcestr": "qsIVR",
    "queuepriority": 10,
    "callerid": "21",
    "calledid": "14",
    "srclineid": "173210d8-fcfc-49f7-b770-d3609445b188",
    "srclinenumber": "17633",
    "srcelementid": "173210d8-fcfc-49f7-b770-d3609445b188"
    "managedlineid": "173210d8-fcfc-49f7-b770-d3609445b188",
    "managedlinenumber": "17633",
    "department": "",
    "isuser": true,
    "userid": "7cf84c23-2736-4fc8-9bf7-bfbb4778fb01",
    "userlogin": "manager2",
    "username": "Виктор Викторыч",
    "istask": false,
    "startqueuetime": "2012-09-28 09:46:33",
    "lenqueue": 41.953125
   }
  ]  
 }
]



Несколько следующих команд предоставляют доступ к функционалу управления звонками, аналогичному доступным для клиентских приложений. Все эти запросы выполняются от имени указанной линии (параметр line), указанного пользователя (параметр user) или указанного рабочего места (параметр wp). Достаточно указания только одного из вышеприведенных параметров. В качестве значения может использоваться guid-идентификатор, название, имя пользователя, логин, номер линии и т.д. По указанному значению однозначно определяется внутренняя линия, от имени которой и исполняется команда.


wp_getchaincontent. Возвращает текущий контент цепочки, в которой участвует линия. Результат представляет собой JSON-структуру.

http://login:password@192.168.0.1:4055/wp_getchaincontent?user=DA803F01-EA77-40FA-BC9D-E2EFB36FD5A8

Пример структуры возвращаемого значения:

{
  "createtime": "2011-07-27 14:41:28",
  "chainid": "c7b333a5-93b3-4277-8c60-9844d63a4732"
  "customfield": "",
  "trace": [
    {
      "contentelementtype": "call",
      "pbxdirection": "internal",
      "objectid": "63d38304-3bff-4e8e-8c42-8f2f11b57c73",
      "objecttype": 0,
      "objecttypestr": "qotQueueLogic",
      "queuesource": 1,
      "queuesourcestr": "qsLineLogic",
      "queuepriority": 10,
      "istask": false,
      "managedlineid": "e76c86ea-a28a-4519-b4ff-8879a92c62b7",
      "isuser": true,
      "userlogin": "Dima",
      "startqueuetime": "2011-07-27 14:41:29",
      "department": "Программисты",
      "callerid": "#999",
      "calledid": "183",
      "srcelementid": "e76c86ea-a28a-4519-b4ff-8879a92c62b7",
      "srclineid": "e76c86ea-a28a-4519-b4ff-8879a92c62b7",
      "srclinenumber": "17002",
      "managedlinenumber": "17002",
      "userid": "2a594b51-bb89-4da6-a69f-f48761baf0d9",
      "username": "Дмитрий Евгеньевич"
    },
    {
      "contentelementtype": "commutation",
      "commutationid": "8fc371f2-ae36-4744-ae7f-bee8c79385a8",
      "connectiontype": 3,
      "connectiontypestr": "ctInnerInner",
      "alineid": "e76c86ea-a28a-4519-b4ff-8879a92c62b7",
      "alinenumber": "17002",
      "aisuser": true,
      "auserid": "2a594b51-bb89-4da6-a69f-f48761baf0d9",
      "auserlogin": "Dima",
      "ausername": "Дмитрий Евгеньевич",
      "aoutnumber": "#999",
      "anumberdialed": "183",
      "atext": "Дмитрий Евгеньевич",
      "blineid": "070aafb0-f47c-4df5-a01f-7bb08ceee269",
      "blinenumber": "17001",
      "bisuser": true,
      "buserid": "7cf84c23-2736-4fc8-9bf7-bfbb4778fb01",
      "buserlogin": "VIKTIRICH",
      "busername": "Виктор Викторыч",
      "boutnumber": "183",
      "bnumberdialed": "",
      "btext": "Виктор Викторыч",
      "timestart": "2011-07-27 14:41:29",
      "timeanswer": "2011-07-27 14:41:31",
      "isrecorded": true
    }
  ]  
}



wp_getabonentinfo. Возвращает информацию о противоположном абоненте в коммутации, в которой участвует линия. Результат представляет собой JSON-структуру

http://login:password@192.168.0.1:4055/wp_getchaincontent?user=ivan

Пример структуры возвращаемого значения:

{
  "currentlinestate": 32,
  "currentlinestatestr": "lsCommutated",
  "abonentinfo": {
    "cansendfiles": false,
    "isconference": false,
    "callerlineid": "070aafb0-f47c-4df5-a01f-7bb08ceee269",
    "callercomment": "",
    "isuser": true,
    "callername": "Виктор Викторыч",
    "canswitchtoconf": false,
    "callerusername": "Виктор Викторыч",
    "commutationid": "21164dde-0c43-46cf-b00f-77bd51cbe284",
    "calleruserlogin": "VIKTIRICH",
    "callerdescription": "",
    "callerlinenum": "17001",
    "isivr": false,
    "callerid": "183",
    "callersimple": "Виктор Викторыч",
    "calleruserid": "7cf84c23-2736-4fc8-9bf7-bfbb4778fb01",
    "canfax": true,
    "canvideo": false,
    "chainid": "b8b552d1-7cb9-4469-a45d-451f27516af1",
    "isextline": false
  }
}



wp_autocallstart. Запускает автодозвон или разовый звонок на указанный номер.

Дополнительные параметры:

  • number - обязательный параметр.
  • direction - необязательный параметр. По умолчанию используется автоопределение (если указанный номер найден среди внутренних номеров, осуществляется звонок вовнутрь, в противном случае осуществляется звонок наружу.
pbx - звонок внутрь,
city - звонок вовне
  • sequence - необязательный параметр. По умолчанию стандартный прямой вызов (direct)
direct - сначала вызывается абонент, после ответа производится обратный вызов линии.
back - сначала осуществляется вызов самой линии, а затем вызов от ее имени указанного номера.

http://login:password@192.168.0.1:4055/wp_autocallstart?line=16038&number=538&direction=pbx



wp_switchcall. Производит flash-переключение текущего звонка на указанный номер. Если линия неактивна, то запускает автодозвон. Все параметры аналогичны wp_autocallstart.



wp_autocallstop. Останавливает активную сессию автодозвона.

http://login:password@192.168.0.1:4055/wp_autocallstop?line=16038



wp_flash. Генерирует flash от имени линии.

http://login:password@192.168.0.1:4055/wp_flash?user=ivan

Дополнительные параметры:

  • mode - Режим переключения, если на удержании уже имеется абонент.
  • abort - отбой текущему, возврат к тому, кто на удержании.
  • switch - возврат к тому, кто на удержании, текущего на удержание
  • next - отбой текущему, переход сразу в набор номера, не возвращаясь к тому, кто на удержании.



wp_declinecall. Отклоняет входящий вызов.

http://login:password@192.168.0.1:4055/wp_declinecall?wp=OPERATOR1



wp_answercall. Отвечает на входящий вызов.

http://login:password@192.168.0.1:4055/wp_answercall?user=ivan



wp_abortcall. Положить трубку. Завершает звонок.

http://login:password@192.168.0.1:4055/wp_abortcall?line=16001



wp_setuserstate. Изменяет текущее состояние пользователя и/или перемещает его из одного режима в другой. В любом случае, если пользователь определен, возвращается ответ 200 OK без дополнительных параметров. Оповещение о смене режимов и состояний протекает в обычном режиме путем событийного оповещения клиентского рабочего места.

Дополнительные параметры:

  • userstateid - определяет новое состояние пользователя. Не все переходы между состояниями возможны, так например, невозможно сделать пользователя свободным, если он занят разговором по телефону, невозможно ввести пользователя в перерыв, если он не находится в режиме call-центра и т.д. Также невозможен перевод пользователя в служебные состояния (отключен, без телефона, зарезервирован и т.д.). Значение параметра указывается в виде числа из набора:
1 - свободен,
2 - перерыв,
3 - нет на месте,
5 - занят в разговоре или в обработчике задачи.
  • onredirect - 0 или 1, определяет активность режима переадресации. Доступно только при выключенном режиме call-центра. Может выставляться как отдельно, так и одновременно с определением других режимов состояния.
  • oncallcenter - 0 или 1, определяет активность режима call-центра. Производит дополнительно смену состояний, если текущее состояние противоречит выбранному режиму (вывод из перерыва при выходе, вывод из переадресации при входе в call-центр).
  • onccmanual - 0 или 1, определяет активность ручного режима в call-центре. Может быть изменено только при нахождении пользователя в call-центре.
  • onlunch - 0 или 1, определяет активность режима перерыва. Доступно только при включенном режиме call-центра. Может выставляться как отдельно, так и одновременно с определением других режимов состояния. При активном режиме перерыва пользователь переводится в состояние перерыва вместо готовности всякий раз, как только освобождается. Вместе с переводом в режим перерыва возможно указание причины и кода причины перерыва (параметры lunchreasonid и lunchreasonmsg) - для регламентированных причин, содержащихся в БД указывается только код, для индивидуальных причин указывается только текст.
  • lunchreasonid - числовой код регламентной причины перерыва (определены в разделе общих настроек).
  • lunchreasonmsg - описание индивидуальной причины перерыва.

http://login:password@192.168.0.1:4055/wp_setuserstate?user=ivanov&userstateid=5

http://login:password@192.168.0.1:4055/wp_setuserstate?user=ivanov&onlunch=1&lunchreasonid=1001