Компоненты работы с данными

Предыдущая статья курса: Базовые компоненты и логика построения сценариев

Общая информация

Для выполнения работы с данными и осуществления сложных операций, в платформе Эра предусмотрен специальный набор компонентов служебных сценариев.

Данные компоненты не связанны друг с другом и реализуют различные механизмы взаимодействия с модулями системы и внешними системами.

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

Детальная техническая информация о компонентах доступна на портале Vendor.

Описания компонентов

Файловая операция

Производит указанную операцию ввода-вывода на диске. Работает с файлами, каталогами, путями.

Компонент имеет дополнительные переходы по ошибкам доступа к файлам.

Свойства компонента

Свойство	Описание
Тип объекта	Определяет тип объекта, над которым производится файловая операция. Возможные значения: Путь (path,1) – Операции со строковым представлением пути. Файл (file,2) – Операции с файлами. Каталог (folder,3) – Операции с каталогами. Содержимое файла (content,4) – Операции с содержимым файла.
Операция	Операция со строковым представлением пути. Возможные значения: Тип пути (getPathType, 101) – Возвращает категорию каталога по указанному пути. Относительный путь (getRelativePath, 102) – Возвращает относительный путь, вырезая из него категорию. Имя файла (getFileName, 103) – Возвращает имя файла из указанного пути. Расширение (getFileExtension, 104) – Возвращает расширение файла из указанного пути. Каталог (getFileDirectory, 105) – Возвращает имя каталога из указанного пути. Построить путь (makePath, 106) – Возвращает путь, собранный из категории каталога и относительного пути, доступный для использования в других операциях и компонентах. Построить путь к файлу (makeFilePath, 107) – Возвращает путь к файлу, собранный из трех аргументов: пути, имени файла и расширения.
Операция	Операция с файлом. Возможные значения: Удалить (deleteFile, 201) – Удаляет файл. Скопировать (copyFile, 202) – Копирует файл. Переместить (moveFile, 203) – Перемещает файл в другой каталог. Проверить наличие (fileExists, 205) – Возвращает 1, если файл существует, иначе 0. Размер (getFileSize, 206) – Возвращает размер файла. Хеш содержимого (getFileHash, 207) – Возвращает хеш содержимого файла. Создать путь (ensureFolder, 208) – Создает каталог для файла по указанному пути, если он не существует. Преобразовать в tiff (fileToFaxTiff, 209) – Преобразует файл в tiff, с параметрами подходящими для компонента Отправка факса Поддерживаемые форматы для преобразования в tiff: bmp, jpg, pdf, png, tiff.
Операция	Операция с каталогом. Возможные значения: Создать (makeFolder, 301) – Создает каталог, если он не существует. Удалить (deleteFolder, 302) – Удаляет каталог. Скопировать (copyFolder, 303) – Копирует каталог со всем содержимым. Переместить (moveFolder, 304) – Перемещает каталог со всем содержимым в другой каталог. Проверить наличие (folderExists, 306) – Возвращает 1, если каталог существует, иначе 0. Количество файлов (getFolderFileCount, 307) – Возвращает количество файлов в каталоге на первом уровне. Количество подкаталогов (getFolderSubfolderCount, 308) – Возвращает количество подкаталогов на первом уровне.
Операция	Операция с содержимым файла. Возможные значения: Создать файл (createFile, 401) – Создает новый файл с указанным содержимым. Записать файл (writeFile, 402) – Записывает новое содержимое в существующий файл. Дописать в конец файла (appendFile, 403) – Добавляет содержимое в конец файла. Считать файл (readFile, 404) – Возвращает содержимое файла. Все операции с содержимым используют указанную кодировку для преобразования из строки в бинарный вид.
Путь	Аргумент, содержащий путь.
Отрезать расширение	Переключатель режима возврата файла без расширения.
Категория каталога	Категория каталога, с использованием которой путь становится доступным для применения в операциях ввода-вывода. Возможные значения: SYNC_COMMON (1) – Каталог общих данных всех доменов в синхронизирующемся между серверами каталоге. SYNC_DOMAIN_COMMON (2) – Каталог общих данных домена в синхронизирующемся между серверами каталоге. SYNC_DOMAIN_DATA (3) – Каталог данных домена в синхронизирующемся между серверами каталоге. SYNC_SCRIPT_DATA (4) – Каталог данных сценария в синхронизирующемся между серверами. SITESHARE_PUBLIC (5) – Каталог общих данных на сетевом диске сайтового хранилища, доступного всем серверам на сайте. SITESHARE_DOMAIN_DATA (6) – Каталог данных домена на сетевом диске сайтового хранилища, доступного всем серверам на сайте. SITESHARE_SCRIPT_DATA (7) – Каталог данных сценария на сетевом диске сайтового хранилища, доступного всем серверам на сайте. GLOBALSHARE_PUBLIC (8) – Каталог общих данных на сетевом диске глобального хранилища, доступного всем сайтам. GLOBALSHARE_DOMAIN_DATA (9) – Каталог данных домена на сетевом диске глобального хранилища, доступного всем сайтам. GLOBALSHARE_SCRIPT_DATA (10) – Каталог данных сценария на сетевом диске глобального хранилища, доступного всем сайтам. TEMP (11) – Временный каталог текущего обработчика сценария. Удаляется через 5 секунд после его завершения.
Относительный путь	Аргумент, содержащий относительный путь.
Имя файла	Аргумент, содержащий название файла.
Расширение	Аргумент, содержащий расширение файла.
Путь источника	Аргумент, содержащий путь источника.
Путь назначения	Аргумент, содержащий путь назначения.
Хеш-функция	Хеш-функция для применения к содержимому файла.
Содержимое	Аргумент с содержимым файла.
Кодировка	Кодировка для применения к содержимому файла при считывании в переменную и наоборот. Возможные значения: Авто (1) – Автоматическое определение. Бинарные данные (binary, 2) – Считывание бинарных данных без преобразования. utf-8 (3) utf-16 (4) utf-32 (5) cp1251 (6) – Кодовая страница windows-1251 (кириллица). Указать название (byname, 7) – Указание имени кодировки.
BOM	Режим считывания содержания файла с учетом префикса кодировки для UTF. Возможные варианты: С BOM (withBOM, 1). Без BOM (withoutBOM, 2).
Endian	Режим раскладки кодировки unicode. Возможные варианты: Little-Endian (littleEndian, 1). Big-Endian (bigEndian, 2).
Название кодировки	Аргумент, содержащий имя применяемой кодировки.

SQL-Запрос

Позволяет производить действия в БД, а также передавать параметры (на вход и на выход).

В качестве параметров выступают переменные сценария.

Подключение к серверу БД осуществляется по строке подключения. Обращение к БД происходит через ODBC и требует наличия в ОС соответствующих драйверов.

В случае ошибки переход осуществляется по ветке «Ошибка», и в переменную «Код ошибки» возвращается соответствующий код исключения БД.

Возврат значений из БД происходит в табличном виде. Сохранение значений в переменные осуществляется по принципу идентичности имен столбцов в последнем из вернувшихся датасетов и переменных сценария. Переменным присваиваются значения из последней строки последнего датасета.

Свойства компонента

Свойства	Описание
База Данных	БД для подключения. Возможные варианты: Проектная (project_psql, 4) – Проектная БД домена (PosgtreSQL), строка подключения к которой берется из настроек домена (settings → project_postgresql_connstr). Другая (other, 2) – Другая БД.
Драйвер	Возможные варианты: ODBC (odbc, 0) – подключение через драйвер ODBC. PSQL (psql, 1) – подключение через внутренний адаптер к PostgreSQL. Для режима указания БД Другая.
Строка соединения	Строка подключения к БД. Для режима указания БД Другая. Пример для odbc драйвера Driver={SQL Server Native Client 11.0}; Server=192.168.0.73,14350; Database=testbase; UID=test; PWD=123; Пример для psql драйвера Driver={PostgreSQL Unicode(x64)}; Server=127.0.0.1; Port=5433; Database=era_dummy_central_common; Uid=platformpgadmin; Pwd=123456; или аналогично формату в конфигурации: host:127.0.0.1,port:5432,login:platformpgadmin,pwd:123456,database:postgres
Время, с	Таймаут на выполнение запроса к БД.
Запрос	Тело SQL-запроса. Пример для ODBC: INSERT INTO EMPLOYEE (NR, FIRSTNAME, LASTNAME, GENDER) VALUES (?, ?, ?, ?) Пример для PSQL: SELECT name as a, birthdate::varchar as b,Where id = $1 or code = $2 Если запрос возвращает таблицу значений из нескольких строк, то в переменные сохраняется произвольная строка. При этом сопоставление значений производится по именам столбцов в датасете выдачи и переменных. Возвращаемые специальные значения null, true, false преобразуются в строковое представление при сохранении в переменные сценария.
Параметры запроса	Списочное значение, устанавливающее параметры для запроса. Порядок параметров строго соответствует порядку применения параметров в запросе.
Кодировка	Кодировка, в которой следует сохранить строковые значения в переменных. Возможные варианты: utf-8 (1) cp1251 (2) – Кодовая страница windows-1251 (кириллица)
Код ошибки	Переменная для сохранения кода ошибки.

WEB-запрос

Позволяет выполнять HTTP- и HTTPS- запросы к web-сервисам по произвольному URL.

Поддерживает HTTP-методы GET, POST, PUT, HEAD, DELETE с контентом и без. Поддерживает отправку асинхронных запросов и запросов с ожиданием ответов.

В случае ошибки переход осуществляется по ветке «Ошибка», и в переменную «Код ошибки» возвращается соответствующий код HTTP.

Компонент поддерживает работу в сессиях, сохраняя и используя cookie, а также HTTPS и подтверждение сертификатов.

Фактическая отправка запроса может производиться как с сервера, на котором работает текущий обработчик сценария, так и с пограничных серверов системы «Era».

В ряде случаев может быть заменено выполнением "curl" запроса через командную строку (компонент Запуск процесса).

Свойства компонента

Свойство	Описание
Прокси	Выключатель использования прокси-сервера.
Аутентификация в прокси	Выключатель прокси-аутентификации.
Логин прокси	Логин к прокси-серверу.
Пароль прокси	Пароль к прокси-серверу.
Адрес прокси	Адрес прокси-сервера.
Порт прокси	Порт прокси-сервера.
Макс. перенаправлений	Ограничение на максимальное число перенаправлений. Значение для HTTP-заголовка Max-Forwards.
URL	URL запроса. Должен содержать схему (например, http://).
Источник запроса	Адрес сервера, с которого необходимо отправить запрос. По умолчанию запрос отправляется с сервера, где обработчик выполняет сценарий. Возможные форматы указания: NodeName NodeName:Iface NodeName@NodeAddr NodeName@NodeAddr:Iface RoleId RoleId:Iface RoleName RoleName:Iface где NodeName – короткое имя ноды в ее полном имени (abc002@192.168.0.12); NodeAddr – адрес ноды в ее полном имени; RoleId – идентификатор роли в конфигурации, по роли определяется нода; RoleName – название роли в конфигурации, по роли определяется нода; Iface – адрес сетевого интерфейса на сервере. При отсутствии ноды/роли, любом некорректном задании имени, отправка производится с сервера, где обработчик выполняет сценарий. При отсутствии или некорректном задании адреса сетевого интерфейса сервера отправителя отправка произойдет с адреса ноды отправителя.
Метод	Возможные варианты: POST (post, 0) GET (get, 1) PUT (put, 2) HEAD (head, 3) DELETE (delete, 4) PATCH (patch, 5) TRACE (trace, 6) OPTIONS (options, 7)
Название: Тип контента Код: contentType Усл. видимости: да По умолчанию: "application/x-www-form-urlencoded"	Значение для HTTP-заголовка Content-Type.
Тело запроса	Содержание тела HTTP-запроса.
Кодировка запроса	Кодировка, с помощью которой производится преобразование тела запроса из строкового представления к бинарному виду перед отправкой. Возможные варианты: unicode (0) utf-8 (1) utf-7 (2) cp1251 (3) – Кодовая страница windows-1251 (кириллица) Указать название (byname, 4) – Задать название кодировки вручную.
Название кодировки запроса	Название кодировки для тела запроса, заданное вручную.
Базовая аутентификация	Выключатель базовой аутентификации.
Логин	Логин для базовой аутентификации.
Пароль	Пароль для базовой аутентификации.
Заголовки	Подставляемые в запрос дополнительные HTTP-заголовки. Аргумент содержит мультистрочное значение, формат каждой из строк: HeaderName: HeaderValue.
Куки	Подставляемые в запрос дополнительные COOKIE. Аргумент содержит мультистрочное значение, формат каждой из строк: Key=Value.
Режим	Режим работы компонента после отправки запроса. Возможные варианты: Ожидание результата (0) – Ожидание ответа вплоть до завершения сценария. Асинхронный запуск (1) – Управление сразу передается следующему компоненту. Обрыв по таймауту (2) – Ожидание ответа в течение установленного времени, по истечению которого HTTP-подключение разрывается и управление передается следующему компоненту. Выход по таймауту (3) – Ожидание ответа в течение установленного времени, по истечению которого управление передается следующему компоненту без разрыва подключения и прерывания процесса отправки.
Время, с	Таймаут ожидания ответа на отправленный HTTP-запрос.
Код ответа	Переменная для сохранения кода HTTP-ответа. Не заполняется, если запрос не отвечен. Если запрос завершен ответом 3xx то инициируется новый переадресованный запрос и код ответа 3хх в дальнейшем перезаписывается.
Заголовки ответа	Переменная для сохранения заголовков HTTP-ответа. Не заполняется, если запрос не отвечен. Если запрос завершен ответом 3xx, то инициируется новый переадресованный запрос, и заголовки в дальнейшем перезаписываются.
Ответ	Переменная для сохранения тела HTTP-ответа. Не заполняется, если запрос не отвечен. Если запрос завершен ответом 3xx, то инициируется новый переадресованный запрос, и тело в дальнейшем перезаписываются.
Кодировка ответа	Кодировка, в которой находится тело HTTP-ответа. Используется для преобразования к строковому представлению в переменной сценария. Возможные варианты: Авто из заголовка (autoheader, 5) Авто из тела (autometaheader, 6) unicode (0) utf-8 (1) utf-7 (2) cp1251 (3) – Кодовая страница windows-1251 (кириллица) Указать название (byname, 4) – Задать название кодировки вручную.
Название кодировки ответа	Название кодировки для тела ответа, заданное вручную.

Доступ к сервису S3

Производит указанную операцию ввода-вывода на хранилище S3.

Свойства компонента

Свойство	Описание
Хранилище	Название хранилища (bucket).
Ключ хранения	Ключ доступа к хранилищу.
Действие	Возможные варианты: Разместить (put, 0) – Размещает файл в хранилище. Скачать (get, 1) – Возвращает содержимое файла, либо скачивает в локальный каталог и возвращает путь к нему. Удалить (delete, 2) – Удаляет файл из хранилища. Размер (size, 3) – Возвращает размер файла в хранилища.
Тип данных	Способ обмена данными сценария с хранилищем Возможные варианты: Массив байтов (binary, 0) – Использует бинарные данные через аргумент или переменную. Файл данных (file, 1) – Использует путь к файлу в локальном каталоге..
Путь к файлу	Путь к файлу в локальном каталоге, с использование одной из файловых категорий.
Данные	Аргумент с содержимым размещаемого в хранилище ресурса.
Буфер	Переменная для сохранения содержимого скачанного из хранилища ресурса.
Заголовки	Дополнительные заголовки для отправки запроса к s3.
Параметры запроса (JSON)	Набор параметров для операции в хранилище, в формате JSON-объекта, где ключи – названия параметров. Возможные значения: параметры запроса
Время, с	Таймаут ожидания ответа, в секундах

Операция с websocket-подключением

Производит одну из операций с websocket-подключением пользователя системы или внешней системы. Подключение должно существовать и быть активным.

Идентификатор подключения формируется модулем обработки websocket-подключений в роли ws и размещается в registrar (роль sr) после авторизации.

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

Свойства компонента

Свойство	Описание
Операция	Выбор операции из списка. Возможные варианты: Отправить сообщение (sendtokenmsg, 0) – Отправляет сообщение в указанное websocket-подключение. Разместить файл для скачивания (ws_temp_file, 1) – Размещает указанный файл на вебсервере, обслуживающем указанное websocket-подключение. Файлу присваивается случайное имя, и компонент возвращает относительный URL. Файл временно доступен для скачивания по HTTP(s) без авторизации в течение 5 минут. Файлы websocktemp (websocktemp, 2) - Производит одно из действий по обмену файлами с временным каталогом сессии на вебсервере, обслуживающем указанное websocket-подключение (категория websocktemp). Файлы доступны внешним приложениям, авторизованным под учетной записью пользователя системы в той же сессии, в которой и указанное websocket-подключение. Файлы доступны через API.
Ид подключения	Идентификатор активного websocket-подключения. Подключение может быть установлено внешней системой с любым из веб-серверов развернутого кластера даже на другом сайте. Идентификатор представляет собой длинную строку и может быть получен из сервиса REGISTRAR поиском по пользователю и названию расширения API (capability), либо как параметр сценария, обрабатывающего входящие подключения.
Направление	Выбор направления из списка. Возможные варианты: Token message (token message, 0) – Отправляется сообщение с кодом message через расширение API для обслуживания websocket-подключений из внешних систем. Token plugin event (token plugin event, 1) – Отправляет сообщение с указанным кодом через указанное расширение API для обслуживания websocket-подключений из внешних систем. User API event (user api event, 2) – Отправляет сообщение с указанным кодом через указанное расширение API для обслуживания пользовательских websocket-подключений.
Название расширения API	Название расширения API, через которое производится отправка указанного сообщения. Это может быть как стандартный модуль, так и любой подключенный плагин-модуль системы, реализующий программный интерфейс для отправки сообщений указанного типа.
Код сообщения	Код сообщения, отправляемого через указанное расширение API. Подставляется в качестве первого элемента JSON-массива, представляющего собой сообщение в протоколе websocket. В зависимости от способа реализации именно этого кода сообщения в расширении API, может отправляться асинхронное сообщение, не требующее ответа, либо синхронный запрос. В этом случае при выборе опции ожидания доставки/ответа появляется возможность получить вместе с ответом данные из удаленной системы.
Тело сообщения	Тело сообщения. Должно соответствовать формату JSON, если иное не определено конкретным расширением API.
Ожидать доставки/ответа	Выключатель синхронного режима ожидания доставки сообщения до приложения адресата. Если выбранный код сообщения в рамках расширения API является запросом, то включение режима предусматривает получение ответа и сохранение его в указанную переменную.
Путь к файлу	Специальный путь к файлу, доступный для обработчика сценариев. Применяется для операции размещения файла на вебсервере.
Действие	Выбор действия из списка в рамках операции обмена файлами с временным каталогом сессии на вебсервере, обслуживающем указанное подключение (категория websocktemp). Возможные варианты: Получить список файлов (get_coll, 0) – Возвращает список файлов во временном каталоге websocktemp вебсервера. Достать файл (get_file, 1) – Достает указанный по имени файл из временного каталога websocktemp вебсервера и сохраняет во временном каталоге текущего сценария. Разместить файл (put_file, 2) – Размещает файл во временном каталоге websocktemp вебсервера. Файл берется по специальном пути, доступному обработчику сценариев. Удалить файл (delete_file, 3) – Удаляет указанный по имени файл из временного каталога websocktemp вебсервера. Применяется для файловой операции с категорией websocktemp.
Путь к файлу	Специальный путь к файлу, доступный для обработчика сценариев. Применяется для файловой операции с категорией websocktemp.
Имя файла	Имя файла для проведения операций обмена файлами с временным каталогом на веб-сервере подключения в рамках категории websocktemp. Применяется для файловой операции с категорией websocktemp.
Время, с	Таймаут ожидания доставки сообщения, в секундах.

LDAP-интеграция

Осуществляет запрос к серверу службы каталогов по протоколу LDAP.

Свойства компонента

Свойство	Описание
Протокол	Протокол подключения к серверу. Возможные варианты: LDAP (ldap, 0) LDAPS (ldaps, 1)
Адреса серверов	Список адресов серверов службы каталогов. В виде строки, где адреса разделены любым символом: запятой, точкой с запятой, пробелом, табуляцией, концом строки. Могут указываться доменные имена, ip-адреса, а также URI, из которых будет доставаться доменное имя. Будет производиться попытка установки соединения с перебором всех адресов до конца или до успеха.
Порт	Порт для коннекта к серверам. По умолчанию 389 для LDAP, 636 для LDAPS.
Сертификат	Для SSL/TLS точек подключения указывает на PEM-файл сертификата, размещенный в каталоге ':SYNC_DOMAIN' или ':SYNC_COMMON'. Файл сертификата может быть загружен, например, в REST-endpoint '/rest/v1/fs/targets/files/certificates/cert.pem' и адресован через ':SYNC_DOMAIN_DATA/files/certificates/cert.pem'. Применяется при переключении LDAP в TLS, а также в LDAPS. Если не указан, то клиентское подключение не будет проверять сертификат сервера на доверенность.
Домен пользователя	Параметр авторизации: домен. Например, Siberia.ttt
Имя пользователя	Параметр авторизации: логин.
Пароль	Параметр авторизации: пароль.
Таймаут, с	Таймаут ожидания выполнения операции, в секундах.
Действие	Варианты операций в службе каталогов. Возможные варианты: Авторизовать (auth, 0) – Простая проверка доступности каталога и правильности авторизационных данных. Найти (search, 1) – Поиск в службе каталогов по указанной строке и требуемым параметрам. Создать (add, 2) – Создание объекта в указанном домене службы каталогов. Удалить (delete, 3) – Удаление объекта в указанном домене службы каталогов. Изменить (modify, 4) – Создание объекта в указанном домене службы каталогов. Изменить пароль (modify_pwd, 5) – Изменение пароля учетной записи. Изменить DN (modify_dn, 6) – Изменение доменного имени.
DN	Название домена, в котором производится операция. Применяется для всех действий, кроме Авторизовать. Например, ou=AD-TEST,dc=Siberia,dc=ttt
Охват	Выбор охвата для операции поиска. Применяется для действия Найти. Возможные варианты: Базовый объект (baseobject, 0) – Только внутри объекта. Только уровень (siglelevel, 1) – По указанному уровню списка, то есть без рекурсии. Ветвь целиком (wholesubtree, 2) – По всему дочернему дереву.
Атрибуты	Атрибуты для поиска. Применяется для действия Найти. Например, objectGUID,cn,telephoneNumber,mobile.
Строка поиска	Строка поиска в службе каталогов. Применяется для действия Найти. Например, present("cn") and present("telephoneNumber") and present("objectGUID") and substrings("mobile",5551234)
Атрибуты	Атрибуты нового или изменяемого элемента. Применяется для действий Создать и Изменить.
Новый пароль	Новый пароль. Применяется для действия Изменить пароль.
Старый пароль	Старый пароль, применяемый для проверки корректности при смене. Применяется для действия Изменить пароль.
Новый DN	Новое имя для элемента. Применяется для действия Изменить DN.
Родительский DN	Родительский элемент. Применяется для действия Изменить DN.

Следующая статья курса: Запуск служебных сценариев

Предыдущая статья курса: Базовые компоненты и логика построения сценариев