Обращение из внешней системы
Вызов действий (Action API)
Платформа предоставляет возможность внешним системам обращаться к разработанной на lsFusion системе с использованием различных сетевых протоколов. Интерфейсом такого взаимодействия является вызов некоторого действия с заданными параметрами и, при необходимости, возврат значений некоторых свойств (без параметров) в качестве результатов. Предполагаются, что все объекты параметров и результатов являются объектами встроенных классов.
Задание действия
Вызываемое действие может задаваться одним из трех способов:
EXEC
- задается имя вызываемого действия.EVAL
- задается код на языке lsFusion. Предполагается, что в этом коде присутствует объявление действия с именемrun
, именно это действие и будет вызвано.EVAL ACTION
- задается код действия на языке lsFusion. Для обращения к параметрам можно использовать спецсимвол$
и номер параметра (начиная с1
).
Протоколы
На данный момент в платформе поддерживаются следующие сетевые протоколы:
HTTP
Взаимодействие по этому протоколу поддерживается как с сервером приложений на порту 7651
, так и с веб-сервером (при наличии такового), на том же порту, на ко тором установлен веб-клиент.
Формат URL, в зависимости от способа задания действия, выглядит следующим образом:
EXEC
-http://адрес сервера:порт/exec?action=<имя действия>
. Параметрaction
всегда должен быть задан.EVAL
-http://адрес сервера:порт/eval?script=<код>
. Если параметрscript
не задан, то предполагается, что код передается первым параметром BODY.EVAL ACTION
-http://адрес сервера:порт/eval/action?script=<код действия>
. Если параметрscript
не задан, то предполагается, что код передается первым параметром BODY.
Параметры
Параметры могут передаваться как в строке запроса (добавлением в ее конец строк формата &p=<значение параметра>
), так и в теле запроса (BODY). При этом предполагается, что для выполняемого действия, сначала подставляются параметры URL (в порядке их следования в запросе), а только потом параметры BODY.
При обработке параметров BODY, параметры с типом контента из следующей таблицы считаются файлами, и передаются в параметры действия в виде объектов файлового класса (FILE
, PDFFILE
и т.п.). При этом в расширение файла записывается соответствующее расширение из упомянутой таблицы. Если тип контента отсутствует в этой таблице, но начинается на application
, то параметр все равно считается файлом, а в расширение этого файла записывается правая часть типа контента (например для типа application/abc
в расширение файла записывается abc
). Параметры с типом контента application/null
считаются равными NULL
.
Параметры BODY с типами контента, отличными от вышеупомянутых, считаются строками, и при вызове автоматически преобразуются к классам параметров вызываемого действия. Пустые строки при этом преобразуются в NULL
.
Заголовки выполняемого запроса автоматически сохраняются в свойство System.headers[TEXT]
. Так, в единственный параметр этого свойства записывается название заголовка, а в значение свойства - значение этого заголовка.
Результаты
Свойства, значения которых необходимо вернуть в качестве результата, передаются в строке запроса, добавлением в ее конец строк формата &return=<имя свойства>
. При этом предполагается, что значения указанных свойств возвращаются в порядке их следования в строке запроса. По умолчанию, если ни одно свойство результата не задано, результирующим свойством считается первое свойство с не NULL
значением из следующего списка.
Если результат запроса является файлом (FILE
, PDFFILE
и т.п.), то тип контента ответа, в зависимости от расширения файла, определяется в соответствии со следующей таблицей. Если расширение файла отсутствует в этой таблице, тип контента устанавливается равным application/<расширение файла>
.
Расширение файла при этом определяется автоматически по аналогии с оператором WRITE
.
Во всех трех верхних случаях, если значение результата равняется NULL
, то вместо расширения файла в тип контента подставляется строка null
(например application/null
), а в качестве самого ответа возвращается пустая строка.
Результаты запроса, отличные от файловых, преобразуются к строкам и передаются с типом контента text/plain
. NULL
значения возвращаются как пустые строки.
Значения свойства System.headersTo[TEXT]
автоматически записываются в заголовки результата запроса. Так, из единственного параметра этого свойства читается название заголовка, а из значения свойства - значение этого заголовка.
Несколько результатов / параметров в BODY
Если BODY запроса имеет тип multipart/*
или application/x-www-form-urlencoded
, то он разбирается на части и каждая из этих частей считается отдельным параметром запроса. При этом порядок этих параметров совпадает с порядком соответствующих частей в BODY запроса.
В свою очередь, если количество возвращаемых результатов больше одного, то:
- Если в запросе есть параметр
returnmultitype=bodyurl
- тип контента ответа при передаче устанавливается равнымapplication/x-www-form-urlencoded
, а результаты кодируются так, как если бы они передавались в строке запроса. - Иначе - тип контента ответа при передаче устанавливается равным
multipart/mixed
, а результаты передаются как составные части этого ответа.
Отметим, что обработка параметров и результатов http запроса во многом аналогична их обработке в обращении к внешней системе по протоколу HTTP (параметры при этом обрабатываются как результаты, и, наоборот, результаты обрабатываются как параметры)
Stateful API
Описанный выше API, по умолчанию, является REST API. Соответственно, сессия изменений создается в момент вызова, а по окончанию этого вызова сразу же закрывается. Однако, в некоторых случаях такое поведение нежелательно, и необходимо накапливать изменения в течении некоторого промежутка времени (например, в процессе ввода информации пользователем), а значит, сессию необходимо сохранять и передавать между вызовами. Для того, чтобы сделать это, при выполнении запроса в конец строки запроса можно добавить строку формата &session=<идентификатор сессии>
, где <идентификатор сессии>
- любая не пустая строка. В этом случае, сессия по окончанию вызову не закроется, а привяжется к переданному идентификатору, и все последующие вызовы с этим идентификатором, будут выполняться в этой сессии. Для того, чтобы закрыть сессию (по окончанию вызова), к ее идентификатору в строке запроса необходимо добавить постфикс _close
(н апример &session=0_close
).
Так как для работы с HTTP сессиями неявно используются cookie, важно не забывать сохранять / передавать cookie между stateful http-вызовами (впрочем, как правило, это делается автоматически, например браузером, HttpClient в Java и т.п.)
В текущей реализации платформы при использовании сессий элементы системы (например локальные свойства) созданные в текущем вызове удаляются, то есть в последующих вызовах не видны.