Skip to end of metadata
Go to start of metadata

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

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

  • 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).

Параметры

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

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

Результаты

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

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

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

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

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

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

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

Язык

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

Примеры

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
 testExportFile = DATA FILE ();

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

    EXTERNAL HTTP 'http://tryonline.lsfusion.org/exec?action=getExamples' PARAMS JSONFILE('\{"mode"=1\}') TO exportFile; // фигурные скобки escape'ся так как используются в интернационализации
    IMPORT FROM exportFile() FIELDS () TEXT caption, TEXT code DO
        MESSAGE 'Example : ' + caption + ', code : ' + code;
        
    EXTERNAL HTTP 'http://tryonline.lsfusion.org/exec?action=doSomething&someprm=$1' BODYURL 'otherprm=$2&andonemore=$3' PARAMS 1,2,'3'; // передает в BODY url-encoded второй и третий параметры
}
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[]'; 
}; 

  • No labels