Перейти к основному содержимому
Версия: 5.x

Обращение к внешней системе (EXTERNAL)

Оператор обращения к внешней системе выполняет заданный код на языке / в парадигме заданной внешней системы. Кроме того этот оператор позволяет передавать объекты встроенных классов, в качестве параметров такого обращения, а также записывать результаты обращения в заданные свойства (без параметров).

На данный момент в платформе поддерживаются следующие типы взаимодействий / внешних систем:

HTTP - выполнение http-запроса Web-сервера​

Для этого типа взаимодействия задается только строка запроса (URL), которая одновременно определяет как адрес сервера, так и непосредственно запрос, который необходимо выполнить.

Параметры​

Параметры могут передаваться как в строке запроса (для обращения к параметру используется спецсимвол $ и номер этого параметра, начиная с 1), так и в его теле (BODY). Предполагается, что в BODY передаются все параметры, не использованные в строке запроса.

При обработке параметров файловых классов (FILE, PDFFILE и т.п.) в BODY, тип контента параметра, в зависимости от расширения файла, определяется в соответствии со следующей таблицей. Если расширение файла отсутствует в этой таблице, тип контента устанавливается равным application/<расширение файла>.

Расширение файла при этом определяется автоматически по аналогии с оператором WRITE.

Во всех трех верхних случаях, если значение параметра равняется NULL, то вместо расширения файла в тип контента подставляется null (например application/null), а в качестве самого параметра передается пустая строка.

Параметры классов, отличных от файловых, преобразуются к строкам и передаются с типом контента text/plain. NULL значения передаются как пустые строки.

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

Результаты​

При обработке ответа запроса, результаты с типом контента из следующей таблицы считаются файлами, и могут записываться только в свойства, класс значений которых равен FILE. При этом в расширение файла записывается соответствующее расширение из упомянутой таблицы. Если тип контента отсутствует в этой таблице, но начинается на application, то результат все равно считается файлом, а в расширение этого файла записывается правая часть типа контента (например для типа application/abc в расширение файла записывается abc). Результаты с типом контента application/null считаются равными NULL.

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

При необходимости, при помощи специальной опции (HEADERSTO), можно записать заголовки полученного ответа запроса в заданное свойство. Это свойство должно иметь ровно один параметр строкового класса, в котором будет храниться название заголовка, и значение строкового класса, в котором будет храниться значение этого заголовка.

Все результаты возвращаются в кодировке UTF-8.

Несколько результатов / параметров в BODY​

Если в BODY передается больше одного параметра, то:

  • Если задана опция BODYURL - тип контента BODY при передаче устанавливается равным application/x-www-form-urlencoded, в качестве BODY передается заданная строка, в которой параметры кодируются так, как если бы они передавались в строке запроса.
  • Иначе - тип контента BODY при передаче устанавливается равным multipart/mixed, а параметры передаются как составные части этого BODY.

В свою очередь, если ответ запроса имеет тип multipart/* или application/x-www-form-urlencoded, то он разбирается на части, и каждая из этих частей считается отдельным результатом выполнения. При этом порядок этих результатов совпадает с порядком соответствующих частей в ответе запроса.

к сведению

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

SQL - выполнение команды SQL-сервера.​

Для этого типа взаимодействия задается строка подключения и SQL-команда(ы), которую необходимо выполнить. Параметры могут передаваться как в строке подключения, так и в SQL-команде. Для обращения к параметру используется спецсимвол $ и номер этого параметра (начиная с 1).

Параметры​

Параметры файловых классов (FILE, PDFFILE и т.п.) можно использовать только в SQL-команде. При этом, если какой-либо из параметров, при выполнении является файлом формата TABLE (TABLEFILE или FILE с расширением table), то такой параметр считается таблицей и в этом случае:

  • перед выполнением SQL-команды, значение каждого такого параметра загружается на сервер во временную таблицу
  • при подстановке параметров, подставляется не само значение параметра, а имя созданной временной таблицы

Результаты​

Результатами выполнения являются: для DML-запросов - числа, равные количеству обработанных записей, для SELECT-запросов - файлы формата TABLE (FILE с расширением table), содержащие результаты этих запросов. При этом порядок этих результатов совпадает с порядком выполнения соответствующих запросов в SQL-команде.

В качестве строки подключения можно использовать предопределенное значение LOCAL. В этом случае подключение будет осуществляться к серверу БД используемому платформой.

LSF - вызов действия другого lsFusion-сервера​

Для этого типа взаимодействия задается строка подключения к lsFusion-серверу (или его веб-серверу, при наличии такового), действие, которые необходимо выполнить, а также список свойств (без параметров), в значения которых будут записаны результаты обращения. Передаваемые параметры должны по количеству и по классам совпадать с параметрами выполняемого действия.

Способ задания действия в этом типе взаимодействия полностью соответствует способу задания действия при обращении из внешней системы.

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

к сведению

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

Язык​

Для объявления действия, обращающегося к внешней системе, используется оператор EXTERNAL.

Примеры​

testExportFile = DATA FILE ();

externalHTTP()  {
    EXTERNAL HTTP GET 'https://www.cs.cmu.edu/~chuck/lennapg/len_std.jpg' TO exportFile;
    open(exportFile());

    // фигурные скобки escape'ся так как используются в интернационализации
    EXTERNAL HTTP 'http://tryonline.lsfusion.org/exec?action=getExamples' PARAMS JSONFILE('\{"mode"=1\}') TO exportFile; 
    IMPORT FROM exportFile() FIELDS () TEXT caption, TEXT code DO
        MESSAGE 'Example : ' + caption + ', code : ' + code;

    // передает в BODY url-encoded второй и третий параметры
    EXTERNAL HTTP 'http://tryonline.lsfusion.org/exec?action=doSomething&someprm=$1' 
             BODYURL 'otherprm=$2&andonemore=$3' 
             PARAMS 1,2,'3'; 
}
externalSQL ()  {
    // получаем все штрих-коды товаров с именем мясо
    EXPORT TABLE FROM bc=barcode(Article a) WHERE name(a) LIKE '%Мясо%'; 

    // читаем цены для считанных штрих-кодов
    EXTERNAL SQL 'jdbc:mysql://$1/test?user=root&password=' 
             EXEC 'select price AS pc, articles.barcode AS brc from $2 x JOIN articles ON x.bc=articles.barcode' 
             PARAMS 'localhost', exportFile() 
             TO exportFile; 

    // для всех товаров с полученными штрих-кодами записываем цены
    LOCAL price = INTEGER (INTEGER);
    LOCAL barcode = STRING[30] (INTEGER);
    IMPORT FROM exportFile() TO price=pc,barcode=brc;
    FOR barcode(Article a) = barcode(INTEGER i) DO
        price(a) <- price(i);
}
externalLSF()  {
    EXTERNAL LSF 'http://localhost:7651' EXEC 'System.testAction[]';
};