Внешние взаимодействия и интеграции
В этом разделе описаны функции для взаимодействия с внешними системами и сервисами, включая HTTP-запросы, SNMP и SSH соединения.
HTTP функции
HTTPRequest
Описание: Расширенная версия функции AutomatonHTTPRequest. В функцию добавлена возможность указать:
- Тип данных
- Кодировку
- Заголовки запроса
- Параметры запроса
- Таймаут запроса
- Параметры прокси
- Параметры сериализации
Inputs
| Название | Тип | Описание |
|---|---|---|
| In | Общие параметры для функций | |
| Url | String | Абсолютный путь к запрашиваемому ресурсу |
| Method | String | HTTP метод запроса |
| Content | Wildcard: Struct array/single | Тело запроса |
| MediaType | String | Тип данных. По умолчанию определяется в зависимости от типа пина Content |
| Encoding | String | Кодировка, которая используется при кодировании контента в запросе. По умолчанию UTF-8 |
| Headers | Struct:StringKeyValue | Список заголовков запроса |
| ContentHeaders | Struct:StringKeyValue | Список заголовков для описания контента. Несет дополнительную информацию о типе контента |
| UrlParameters | Struct:StringKeyValue | Список параметров запроса |
| RequestTimeoutSeconds | Integer | Таймаут запроса в секундах. При указании 0, используется значение по умолчанию = 60 секунд. |
| ProxyConfiguration | Struct:ProxyConfiguration | Конфигурация подключения с использованием прокси-сервер (адрес, порт, пользователь и пароль). |
| JsonSerializationSettings | Struct:JsonSerializationSettings | Настройка сериализации ключей тела ответа/запроса |
Справка по JsonSerializationSettings
Структура JsonSerializationSettings содержит следующие переменные:
- UseCamelCase (Boolean): включает преобразование ключей в CamelCase в пине
Contentпри сериализации и в пинеResultпри десериализации - PropertyNameCaseInsensitive (Boolean): включает преобразование ключей в CamelCase в пине
Resultпри десериализации. Тип пинаResultпри этом должен быть существующей структурой.
Пример работы PropertyNameCaseInsensitive: в структуре пинаResultсуществует параметр "numCase". Если будет включена настройка и вResultпридет "NUMCASE", то значение попадет в "numCase". При отключенной настройке значение останется пустым.
Включать имеет смысл только при отключенномUseCamelCase.
Outputs
| Название | Тип | Описание |
|---|---|---|
| Ok, Failed, Response | Общие параметры для функций | |
| Result | Wildcard: Struct array/single | Результат запроса будет передан для исходящего пина Result, формат которого будет определен по установленной связи Wildcard |
AutomatonHTTPRequest
Описание: Функция позволяет сформировать http-запрос для обращения к публичному API системы.
Для формирования запроса, необходимо указать:
- адрес API
Если Uri не начинается с
http://или сhttps://, то автоматически будет подставленBaseUriиз переменнойScenarioдля удобства работы с API Monq. - метод запроса
- тело запроса
Inputs
| Название | Тип | Описание |
|---|---|---|
| In, BearerToken | Общие параметры для функций | |
| Url | String | Адрес API |
| Method | String | Тип (метод) запроса |
| Body | Wildcard: Struct array/single | Тело запроса |
Outputs
| Название | Тип | Описание |
|---|---|---|
| Ok, Failed, Response | Общие параметры для функций | |
| Result | Wildcard: Struct array/single | Результат запроса будет передан для исходящего пина Result, формат которого будет определен по установленной связи Wildcard |
Функции SNMP & SSH
SNMPRequestV1V2
Описание: Функция позволяет формировать SNMP-запросы для обращения к сетевым устройствам
Inputs
| Название | Тип | Описание |
|---|---|---|
| In | Общие параметры для функций | |
| Configuration | Struct:SNMPConfiguration | Конфигурация подключения |
| OID | String | Идентификатор объекта |
| Version | Enum (v1/v2) | Версия протокола SNMP |
| Method | Enum (get/set/walk) | Метод запроса |
| Data | Struct:SNMPData | Определение типа входящих данных при использовании метода Set |
| WalkMode | Enum (Default/WithinSubtree) | Режим обхода, имеет смысл только если в параметре Method выбран Walk |
Outputs
| Название | Тип | Описание |
|---|---|---|
| Out | Exec | Последовательность активна в случае успешного выполнения запроса |
| Failed | Exec | Последовательность активна если запрос выполнен с ошибкой |
| Response | Struct:SNMPResponse | Возвращает результат запроса согласно модели SNMPResponse |
| Error | String | Возвращает текст ошибки |
Struct:SNMPConfiguration
Описание структуры Struct:SNMPConfiguration:
| Пин | Тип | Описание |
|---|---|---|
| IPAddress | String | Адрес сервера (IP-адрес, либо DNS-имя) |
| Port | Integer | Номер порта оборудования |
| Community | String | Пароль |
| TimeoutSeconds | Integer | Таймаут подключения (по умолчанию 60 секунд) |
| MaxRepetition | Integer | Указывает, сколько строк таблицы должно быть получено за одну операцию (применимо к SNMPv2 и методу walk) |
Struct:SNMPData
Описание структуры Struct:SNMPData:
| Пин | Тип | Описание |
|---|---|---|
| Type | Enum | Определение типа входящих данных |
| Data | String | Данные |
| Id | String | OID внутри оборудования |
Struct:SNMPResponse
Описание структуры Struct:SNMPResponse:
| Пин | Тип | Описание |
|---|---|---|
| OID | String | Идентификатор объекта |
| Data | Struct:SNMPData | Данные |
SSHRequest
Описание: Функция позволяет установить SSH соединение и выполнить команды на удаленном хосте
Inputs
| Название | Тип | Описание |
|---|---|---|
| In | Общие параметры для функций | |
| Configuration | Struct:SSHConfiguration | Конфигурация подключения |
| Command | String | Текст отправляемой команды |
Outputs
| Название | Тип | Описание |
|---|---|---|
| Out | Exec | Последовательность активна в случае успешного выполнения запроса |
| Failed | Exec | Последовательность активна если запрос выполнен с ошибкой |
| Result | String | Возвращает результат выполнения команды |
| Error | String | Возвращает текст ошибки |
Struct:SSHConfiguration
Описание структуры Struct:SSHConfiguration:
| Пин | Тип | Описание |
|---|---|---|
| Host | String | Адрес сервера (IP-адрес, либо DNS-имя) |
| Port | Integer | Номер порта SSH |
| Username | String | Имя пользователя |
| Password | String | Пароль для аутентификации пользователя (опционально, может быть пустым, если аутентификация через PrivateKey) |
| PrivateKey | String | Закрытый ключ для установления соединения (опционально, может быть пустым, если аутентификация через Password) |
- Если передан и пароль и закрытый ключ, то функция отрабатывает по закрытому ключу
- Поддерживаются только RSA ключи в PEM-формате без Passphrase
Функции отправки сообщений
SendEmail
Назначение: Отправка почтовых сообщений
Описание: Функция позволяет отправить письмо через указанный SMTP сервер
Inputs
| Название | Тип | Описание |
|---|---|---|
| In | Общие параметры для функций | |
| Message | Struct:EmailMessage | Модель сообщения |
| Configuration | Struct:EmailConfiguration | Модель конфигурации |
Outputs
| Название | Тип | Описание |
|---|---|---|
| Ok, Failed | Общие параметры для функций | |
| Error | String | Текст ошибки, в случае ее возникновения |
Struct - EmailMessage
Описание структуры Struct:EmailMessage:
| Пин | Тип | Описание |
|---|---|---|
| Subject | String | Тема письма |
| Body | String | Текст письма |
| MailType | String | Формат письма (plain/html) |
| Recipients | String (array) | Список адресов получателей |
Struct - EmailConfiguration
Описание структуры Struct:EmailConfiguration:
| Пин | Тип | Описание |
|---|---|---|
| FromName | String | Имя отправителя |
| FromEmail | String | Адрес отправителя |
| Host | String | Адрес SMTP сервера |
| Port | Integer | Порт сервера |
| Username | String | Имя пользователя |
| Password | String | Пароль пользователя |
| SecureMode | String | Режим шифрования (TLS/SSL) |
SendEmailExtended
Назначение: Отправка почтовых сообщений через Подключения типов действий
Описание: Функция позволяет отправить письмо через настроенное подключение в Типе действий
Inputs
| Название | Тип | Описание |
|---|---|---|
| In | Общие параметры для функций | |
| ConnectionCreds | Struct:ConnectionsStructApi | Модель подключения |
| Message | Struct:EmailMessage | Модель сообщения |
| DefaultCreds | Struct:EmailConfiguration | Модель конфигурации |
Outputs
| Название | Тип | Описание |
|---|---|---|
| Ok, Failed | Общие параметры для функций | |
| Error | String | Текст ошибки, в случае ее возникновения |
Struct - ConnectionsStructApi
Описание структуры Struct:ConnectionsStructApi: Служебная структура для передачи в функцию SendEmailExtended параметров подключения.
Struct - EmailMessage Ext
Описание структуры Struct:EmailMessage:
| Пин | Тип | Описание |
|---|---|---|
| Subject | String | Тема письма |
| Body | String | Текст письма |
| MailType | String | Формат письма (plain/html) |
| Recipients | String (array) | Список адресов получателей |
Struct - EmailConfiguration Ext
Описание структуры Struct:EmailConfiguration:
| Пин | Тип | Описание |
|---|---|---|
| FromName | String | Имя отправителя |
| FromEmail | String | Адрес отправителя |
| Host | String | Адрес SMTP сервера |
| Port | Integer | Порт сервера |
| Username | String | Имя пользователя |
| Password | String | Пароль пользователя |
| SecureMode | String | Режим шифрования (TLS/SSL) |
SendTelegramMessage
Назначение: Отправка сообщений через Telegram
Описание: Функция взаимодействия с API Telegram для отправки текстовых сообщений
Inputs
| Название | Тип | Описание |
|---|---|---|
| In | Общие параметры для функций | |
| BotToken | String | Токен Telegram-бота |
| ChatId | String | Идентификатор чата в Telegram |
| Message | Struct:TelegramMessage | Модель сообщения |
Outputs
| Название | Тип | Описание |
|---|---|---|
| Ok, Failed | Общие параметры для функций | |
| Result | Wildcard | Ответ запроса |
| Response | Struct:HttpResponse | Возвращает результат выполнения запроса согласно модели HttpResponse |
Struct - TelegramMessage
Описание структуры Struct:EmailMessage:
| Пин | Тип | Описание |
|---|---|---|
| Text | String | Текст сообщения |
| ParseMode | String | Режим парсинга сообщения Telegram parse_mode |
| DisableWebPagePreview | Bool | Отключение пред-просмотра ссылок в сообщении |
| DisableNotification | Bool | Отключение уведомления для сообщения |
| ProtectContent | Bool | Установка запрета на пересылку сообщения |
SendTelegramMessageExtended
Назначение: Отправка сообщений через Telegram
Описание: Функция взаимодействия с API Telegram для отправки текстовых сообщений
Inputs
| Название | Тип | Описание |
|---|---|---|
| In | Общие параметры для функций | |
| ConnectionCreds | Struct:ConnectionsStructApi | Модель подключения |
| Recipients | String(array) | Список получателей (Telegram ChatId) |
| Message | Struct:TelegramMessage | Модель сообщения |
| DefaultCreds | Struct:TelegramCreds | Модель конфигурации |
| ProxyConfiguration | Struct:ProxyConfiguration | Модель конфигурации прокси-сервера |
Outputs
| Название | Тип | Описание |
|---|---|---|
| Ok, Failed | Общие параметры для функций | |
| Result | Dynamic (array) | Массив результатов выполнения каждого запроса в отдельности |
| Response | Struct:HttpResponse | Возвращает результат выполнения запроса согласно модели HttpResponse |
Struct - TelegramCreds
Описание структуры Struct:TelegramCreds:
| Пин | Тип | Описание |
|---|---|---|
| Token | String | Токен Telegram-бота |
Struct - ProxyConfiguration
Описание структуры `Struct:ProxyConfiguration:
| Пин | Тип | Описание |
|---|---|---|
| Address | String | Адрес сервера |
| Port | Integer | Порт сервера |
| Username | String | Пользователь |
| Password | String | Пароль |
SendImageTelegram
Назначение: Отправка сообщений через Telegram
Описание: Функция взаимодействия с API Telegram для отправки текстовых сообщений
Inputs
| Название | Тип | Описание |
|---|---|---|
| In | Общие параметры для функций | |
| BotToken | String | Токен Telegram-бота |
| ChatId | String | Идентификатор чата в Telegram |
| Image | Struct:TelegramImage | Модель вложения |
Outputs
| Название | Тип | Описание |
|---|---|---|
| Ok, Failed | Общие параметры для функций | |
| Result | Wildcard | Ответ запроса |
| Response | Struct:HttpResponse | Возвращает результат выполнения запроса согласно модели HttpResponse |
Struct - TelegramImage
Описание структуры Struct:TelegramImage:
| Пин | Тип | Описание |
|---|---|---|
| ImageUri | String | Публичная ссылка на изображение |
| Bytes | Byte (array) | Массив байт изображения. Если указан ImageUri данный параметр игнорируется |
| FileName | String | Имя файла. Если оставить пустым будет задано дефолтное название Image |
| Caption | String | Описание изображения |
| Settings | Struct:TelegramImageSettings | Модель дополнительных настроек |
Struct - TelegramImageSettings
Описание структуры Struct:TelegramImageSettings:
| Пин | Тип | Описание |
|---|---|---|
| ParseMode | String | Режим парсинга сообщения Telegram parse_mode |
| HasSpoiler | Bool | Защита изображение спойлером. Изображение будет видно после нажатия на спойлер. |
| DisableNotification | Bool | Отключение уведомления для сообщения |
| ProtectContent | Bool | Установка запрета на пересылку сообщения |
Вспомогательные функции для рассылок
FilterRecipients
Назначение: Вспомогательная функция фильтрации получателей из рассылки
Описание: Функция возвращает результат, согласно переданной в настройках действия рассылки (или нескольких рассылок)
Inputs
| Название | Тип | Описание |
|---|---|---|
| In | Общие параметры для функций | |
| RecipientsList | Struct:RecipientsListStructApi (Array) | Массив моделей рассылок, получаемых из входной модели действия |
Outputs
| Название | Тип | Описание |
|---|---|---|
| Ok, Failed | Общие параметры для функций | |
| Result | Struct:FilterRecipientsResult (Array) | Модель подключения, которое указано для рассылки и список контактов |
| Error | String | Текст ошибки в случае выполнения запроса с ошибкой |
Пример использования
Struct - FilterRecipientsResult
Описание структуры Struct:FilterRecipientsResult:
| Пин | Тип | Описание |
|---|---|---|
| Recipients | String (array) | Список контактов из рассылки |
| Connection | Struct:ConnectionsStructApi | Модель, используемого подключения в рассылке РГ |
GetConnectionCreds
Назначение: Вспомогательная функция получения данных подключения
Описание: Функция возвращает данные, определенные в качестве параметров подключения в типе действий
рекомендуем использовать данную функцию только при создании глобальных функций в собственных библиотеках автоматона
Inputs
| Название | Тип | Описание |
|---|---|---|
| In | Общие параметры для функций | |
| BearerToken | String | Токен пользователя с правами администратора |
| Connection | Struct:ConnectionsStructApi | Модель, используемого подключения в рассылке РГ |
Outputs
| Название | Тип | Описание |
|---|---|---|
| Ok, Failed | Общие параметры для функций | |
| Result | Wildcard | Необходимо выбрать созданную структуру подключения, которая задействована в рассылке |
| Error | String | Текст ошибки в случае выполнения запроса с ошибкой |
Пример использования
Пример структуры подключения из библиотеки Libs_us1.NotificationService:
GetContacts
Назначение: Системная функция получения контактных данных пользователей
Описание: Функция используется при автоматическом создании функций рассылок, чтобы получить контактные данные для конкретных пользователей, согласно переданному типу контакта
Inputs
| Название | Тип | Описание |
|---|---|---|
| In | Общие параметры для функций | |
| BearerToken | String | Токен пользователя с правами администратора |
| ContactId | Integer64 | Идентификатор контакта, который указан для подключения и по которому создана рассылка |
| UserIds | Integer64 (Array) | Массив идентификаторов пользователей, у которых из профилей будет забираться контактная информация |
Outputs
| Название | Тип | Описание |
|---|---|---|
| Ok, Failed | Общие параметры для функций | |
| Contacts | String (Array) | Массив строк с контактными данными |
| Response | Struct:AutomatonResponse | Возвращает результат выполнения запроса согласно модели AutomatonResponse |
FilterUserIds
Назначение: Системная функция получения контактных данных пользователей при использовании ролей в рассылках
Описание: Функция используется при автоматическом создании функций рассылок, чтобы получить контактные данные для конкретных пользователей, согласно выбранной роли
Inputs
| Название | Тип | Описание |
|---|---|---|
| In | Общие параметры для функций | |
| RoleIds | Integer64 (Array) | Массив идентификаторов ролей пользователей в РГ |
Outputs
| Название | Тип | Описание |
|---|---|---|
| Ok, Failed | Общие параметры для функций | |
| UserIds | Integer64 (Array) | Массив идентификаторов пользователей, у которых в текущей РГ есть роли, переданные на вход |