Задания потоков данных
Для интеграции с внешними Информационными системами, где требуется получение данных по технологии pull
, предусмотрены:
- Пользовательские задания - для создания собственных интеграций и получения данных по ним.
Технология pull
(англ. pull technology, pull coding или client pull - сбор чего-либо ) - технология сетевой коммуникации, при которой первоначальный запрос данных производится клиентом, а ответ порождается сервером.
Задание представляет собой сценарий, написанный на языке разметки Yaml
.
Результатом выполнения сценария является "артефакт" - далее передаваемый в Поток данных Monq через REST API.
Задания Потоков данных могут выполнятся на:
- системном Агенте - представлен в виде внутреннего микросервиса
- внешнем Агенте (руководство по подключению внешнего Агента)
Пользовательские задания
Пользовательские Задания Потоков данных необходимы для реализации интеграций с внешними Информационными системами, которые необходимо подключить к Monq для перетекания событий.
Для создания интеграции с внешней Информационной системой необходимо:
-
Создать Поток данных
-
Добавить Задание на вкладке Конфигурация Потока данных
-
Разработать сценарий Задания, которое будет исполнятся на подключенном Агенте
-
Сохранить и запустить Поток данных
Синтаксис заданий "Потоков данных" monq
Сценарий — это настраиваемый автоматизированный процесс, состоящий из одного или нескольких заданий (Job).
Чтобы определить конфигурацию вашего сценария необходимо создать "Задание" для Потока данных.
Задания Потоков данных используют синтаксис языка YAML. Редактирование сценария производится в интерфейсе Monq.
jobs
Запуск сценария состоит из одного или нескольких заданий, которые по умолчанию выполняются параллельно. Каждое задание выполняется в среде Агента Monq.
Поля сценария
Название | Тип | Обязательно | Шаблон | Описание |
---|---|---|---|---|
name | строка | - | - | Название сценария |
env | произвольный словарь | - | + | Глобальные переменные окружения, доступные в любом месте сценария. |
settings | объект настроек | - | - | Настройки выполнения сценария. |
jobs | массив служебных работ | + | - | Служебные работы сценария, выполняющиеся параллельно. |
Поля служебных работ
Название | Тип | Обязательно | Шаблон | Описание |
---|---|---|---|---|
name | строка | - | - | Название служебной работы |
env | произвольный словарь | - | + | Переменные окружения, доступные в любом месте служебной работы. Значения перетирают значения совпадающих ключей в словаре сценария. |
settings | объект настроек | - | - | Настройки выполнения служебной работы. |
steps | массив шагов | + | - | Шаги служебной работы сценария, выполняющиеся последовательно. |
store | произвольный словарь | - | + | Сохраняемые в глобальном кэше переменные, значения которых передаются в следующий запуск сценария. Значения перетирают значения совпадающих ключей в словарях шагов. Также значения совпадающих ключей перетираются значениями в словарях других служебных работ, выполненных позже. |
artifacts | массив артефактов | - | - | Сформированные артефакты выполнения служебной работы. |
Поля шага служебной работы
Название | Тип | Обязательно | Шаблон | Описание |
---|---|---|---|---|
name | строка | - | - | Название шага служебной работы. |
env | произвольный словарь | - | + | Переменные окружения, доступные в любом месте шага служебной работы. Значения перетирают значения совпадающих ключей в словарях сценария и служебной работы. |
settings | объект настроек | - | - | Настройки выполнения шага служебной работы. |
run | строка | + | + | Консольная команда для исполнения на агенте. |
plugin | строка | + | + | Команда агентского плагина для исполнения на агенте. |
with | произвольный словарь | - | + | Переменные исполняемой команды. |
with-secured | произвольный словарь | - | + | Защищённые переменные исполняемой команды, значения которых скрываются в логах. |
outputs | произвольный словарь | - | + | Возвращаемые значения. |
store | произвольный словарь | - | + | Сохраняемые в глобальном кэше переменные, значения которых передаются в следующий запуск сценария. |
Поля настроек
Название | Тип | Обязательно | Шаблон | Описание |
---|---|---|---|---|
shell | строка | - | - | Оболочка ОС. Может быть указан либо путь к исполняемому файлу, либо одно из предзаданных значений. |
Предзаданные значения оболочек
Значение | Заменяющая команда |
---|---|
cmd | cmd.exe /C <command> |
bash | bash -c "<command>" |
powershell | powershell.exe -Command <command> |
pwsh | pwsh -Command <command> |
sh | sh -c '<command>' |
Для различных семейств ОС используются значения по умолчанию:
- Windows —
cmd
- Unix —
bash
В остальных случаях нужно обязательно явно указать желаемую оболочку.
Поля артефакта
Название | Тип | Обязательно | Шаблон | Описание |
---|---|---|---|---|
name | строка | - | - | Название артефакта. |
paths | массив ст рок | - | + | Пути к файлам, которые будут помещены в один архив. |
files | массив строк | - | + | Список путей к файлам, которые будут переданы отдельно. |
data | произвольный объект | - | + | Данные артефакта. |
send-to | объект настроек отправки артефакта | - | - | Настройки отправки данных артефакта. |
Данные артефакта
В поле data
пользователи, при написании сценария могут сформировать модель события которое будет отправлено в коллектор Monq.
При отправке различных типов данных через артефакт, следует учитывать характер конкретного типа и способы использования шаблонизатора.
Например, если у нас имеется следующее событие, хранящееся в переменной outputs.test.responseData
:
{
"string": "text",
"number": 123,
"arrayString": ["test1", "test2", "123"],
"arrayNumber": [1, 2, 3],
"boolean": false,
"null": null,
"object": {
"string": "text",
"number": 123,
"array": ["test1", "test2", "123"],
"boolean": false,
"null": null
}
}
-
string
- чтобы отправить значение поля с типомstring
, его нужно обязательно заключать в кавычки, иначе данные будут конвертированы в невалидныйjson
и соответственно не будут отправлены. Пример использования:artifacts:
- data: >
{
"string": " {{ outputs.test.responseData.string }} "
} -
arrayString
,object
,number
,boolean
- чтобы отправить значение поля с одним из перечисленных типов, нужно воспользоваться следующей конфигурацией (без использования кавычек):artifacts:
- data: >
{
"object": {{ outputs.test.responseData.object }}
} -
null
- для обработки исключений с пустыми полями, можно воспользоваться следующей конфигурацией:artifacts:
- data: >
{
"null": {% if outputs.test.responseData.null == nil %} null {% endif %}
}
Поля настроек отправки артефакта
Название | Тип | Обязательно | Шаблон | Описание |
---|---|---|---|---|
monq | объект настроек отправки в monq | - | - | Настройки отправки в monq. |
api | объект настроек API запроса | - | - | Настройки отправки через API запрос. |
Поля настроек отправки в monq
Название | Тип | Обязательно | Шаблон | Описание |
---|---|---|---|---|
keys | массив строк | - | - | Специальные системные ключи. |
Поля настроек API запроса
Название | Тип | Обязательно | Шаблон | Описание |
---|---|---|---|---|
method | строка | - | + | Метод запроса. По умолчанию POST . |
uri | строка | - | + | URI запроса. |
headers | произвольный словарь | - | + | Заголовки запроса. |
query-params | произвольный словарь | - | + | Параметры запроса. |
media-type | строка | - | + | Тип тела запроса. По умолчанию application/json . |
Минимальная структура сценария
Для каждого YAML сценария должна быть определена минимальная структура в одной из следующих вариаций:
jobs:
- steps:
- run: echo Hello!
jobs:
- steps:
- plugin: pluginName
jobs:
- steps:
- plugin: pluginName
run: echo Hello!
Если указаны и команда плагина
plugin
, и консольная командаrun
, то сначала выполнится плагин, а потом последовательно выполнится консольная команда.
Шаблонизация
В некоторых полях сценария поддерживается указание шаблонов. В шаблонах можно обращаться к различным группам переменных.
Доступно несколько шаблонизаторов:
jobs:
- steps:
- run: date /c
store:
currentDate: $._outputs.shell
jobs:
- steps:
- run: date /c
store:
currentDate: {{ _outputs.shell }}
Группы переменных
-
env
— переменные окружения. Имеют область видимости в зависимости от места, в котором определены. -
vars
— переменные агентского задания. В неявном виде может передаваться информация о владельце задания:stream
— поток данных:
{
"id": 0,
"name": "",
"key": "00000000-0000-0000-0000-000000000000",
"params": {
"key": "value"
}
} -
storage
— перем енные глобального кэша. -
Системные переменные:
userspaceId
— идентификатор пользовательского пространства.baseUri
— URL адрес текущего пространства Monq (например,https://monq.example.com/
).
-
outputs
— возвращаемые переменные служебной работы. Имеют область видимости в соответствующей служебной работе. -
_outputs
— возвращаемые переменные шага служебной работы. Имеют область видимости на соответствующем шаге служебной работы. По завершении шага переменные совмещаются с переменными соответствующей служебной работы. Содержат предзаданные переменные:shell
— вывод успешно выполненной консольной команды.
Примеры сценариев
Ниже приведены примеры сценариев для использования в Заданиях потоков данных.