Модуль реализации блоков на Python
8 800 555-89-02
Войти
Для разработчиков
CTRL+K
Standalone2502

Модуль реализации блоков на PythonBETANEW

В этой статье

Пользовательские блоки Python являются расширением агента автоматизации и предоставляют возможность использовать язык Python и его библиотеки для решения сложных задач. С их помощью можно создавать собственные скрипты, расширяя функциональность платформы через разработанный Python SDK.

Структура каталогов в контейнере

Структура каталогов в контейнере следующая:

  • sdk — системные скрипты и абстракции
  • packages — директория с пользовательскими пакетами
  • entrypoint.py — точка входа в реализацию пакетов
  • requirements.txt — зависимости системных скриптов

Старт модуля

При старте модуля все скрипты, указанные в конфигурационном файле com.infomaximum.subsystem.automationagentextpy.json, запускаются с аргументом --get-info. Запуск скрипта подтверждается появлением команды в выходном потоке stdout.

{"cmd":"start"}

Пример ожидаемого ответа в stdout:

{
    "uuid":"ed2af80c-4a98-4357-b778-5dbcec926a85",
    "data": {
        "mode": "isolated",
        "protocol_version": 1,
        "groups": [{
            "uuid": "test_group_17d80e527c6eb4cb9b9cc4031378ae176",
            "name": {
                "en": "Testing group info",
                "ru": "Тестовая группа"
            },
            "category":"tools",
            "icon":"pictures/test_group_17d80e527c6eb4cb9b9cc4031378ae176.png",
            "blocks": [{
                "uuid": "test_block_9865a4f37154458fbe98daaa32d0cc77",
                "type": "action",
                "name": {
                    "en": "Testing block info",
                    "ru": "Тестовый блок"
                },
                "description": {
                    "en": "Testing block description",
                    "ru": "Описание тестового блока"
                },
                "compatible_connections": [
                    "connection_422178d485924ee89121d4e7b992f918"
                ],
                "fields": "[{key:'var_1',type:'text',label:'Введи 1 число',description:\"Поле для ввода первого числа\",required:true},{key:'var_2',type:'text',label:'Введи 2 число',description:\"Поле для ввода второго числа\",required:true},{key:'sw_1',type:'switcher',label:'Просто пример свитчера',required:true},(z,bundle) => {if (bundle.inputData.sw_1) {return [{key:'f_1',type:'text',label:'Поле 1 из набора 1',required:false},{key:'f_2',type:'text',label:'Поле 2 из набора 1',required:false}];} else {return [];}}]"
            }],
            "connections": [{
                "uuid": "connection_422178d485924ee89121d4e7b992f918",
                "name" : {
                    "en" : "Testing connection info",
                    "ru" : "Тестовое подключение",
                },
                "description" : {
                    "en" : "Testing connection description",
                    "ru" : "Описание тестового подключения",
                },
                "fields" :"[{key:'var_1',type:'textPlain',label:'Введи число',description:'Поле для ввода 1',required:true},{key:'var_2',type:'textPlain',label:'Введите что-нибудь',description:'Поле для ввода 2',required:true}]"
            }]
        }],
    }
}

Где

  • data — основные данные, которые содержат информацию о группе, блоках и подключениях
    • mode — режим запуска блоков (interactive/isolated)
    • protocol_version — версия протокола
    • groups — массив групп
      • uuid — уникальный идентификатор группы. Для уникальности идентификаторов используйте сгенерированный UUID
      • name — локализованное название группы
        • en — на английском
        • ru — на русском
      • icon — путь к файлу иконки группы относительно папки скрипта
      • category — категория верхнего уровня, в которую попадают блоки. Доступны следующие значения: "databases", "storages", "services", "tools"
      • blocks — массив блоков
        • uuid — уникальный идентификатор блока
        • type — тип блока (action/trigger)
        • name — локализованное название блока
          • en — на английском
          • ru — на русском
        • description — локализованное описание блока
          • en — на английском
          • ru — на русском
        • compatible_connections — список UUID-подключений, которые совместимы с блоком
        • fields — строка с описанием полей блока. Представляет собой JS-код, который описывает поля для ввода данных, и прочие элементы управления профиля блока. Соответствует описанию пользовательских интеграций
      • connections — массив подключений
        • uuid — уникальный идентификатор подключения
        • name — локализованное название подключения
        • description — локализованное описание подключения
          • en — на английском
          • ru — на русском
        • compatible_connections — список UUID-подключений, которые совместимы с блоком
        • fields — строка с описанием полей подключения. Представляет собой JS-код, который описывает поля для ввода данных, и прочие элементы управления профиля блока. Соответствует описанию пользовательских интеграций

Если вышеописанные параметры указаны некорректно или отсутствуют, то в системе возникает исключение.

Режим изолированных запусков

Каждый запуск скрипта связан с сессией (потоком). Особенности работы системы Request-Response:

  1. Для каждого запроса генерируется уникальный идентификатор.
  2. Каждый запрос отправляется в отдельном потоке.
  3. Запрос и ответ — однострочные, переводы строк экранируются.

Старт сессии

Заметка

При запуске блока запускается скрипт. Также это обозначает старт сессии обработки данных.

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

Аргументы запуска:

--start
--vault-path "/var/lib/infomaximum/temp/com.infomaximum.subsystem.pythonextension/=<uuid>"
--block-uuid "some_block_4345f5709cbb4a8486d800b2908168bf"
--input-data {
    "data": {      
        "static_fields": [{        
            "name": "field1",
            "value": "value1"
        },{
            "name": "field3",
            "value": 3
       }],
        "dynamic_field_names": ["StringField1", "FrequencyDoubleField", "ObjectField3", "LongArrayField4", "FileContentField5"],
        "execution_mode": "DEBUG_BLOCK",
        "connection_fields": [{
            "name": "host",
            "value": "115.151.51.1"
        },{
            "name": "port",
            "value": 1088
        },{
            "name": "token",
            "value": "TIh3YEFigvdF1DiDdmASZNPD8tJjYvFOhqtW6TWirKKdLBBlL75TXnO5jr4Z577aTsf1MLLJDPTpeMk4uJt5MGVz3jARBznWaZVtaEQXL0YWvAng5f8K"
        }]
    },
    "uuid": "a1db9946-2454-423f-a76e-fd8a6e815f97"
}

Где

  • --start — команда запуска сессии обработки данных
  • --vault-path — путь к хранилищу данных
  • --block-uuid — идентификатор блока
  • --input-data — входные данные в формате JSON
    • uuid — уникальный идентификатор запроса
    • static_fields — поля, значения которых не меняются между записями входящих данных, т.е. не содержат маппинг
    • dynamic_field_names — список имен полей, значения которых меняются между записями входящих данных, т.е. содержат маппинг
    • execution_mode — режим выполнения
      • SIMPLE_EXECUTION — обычное выполнение опубликованного скрипта
      • DEBUG_FULL — полное тестирование скрипта
      • DEBUG_BLOCK — режим тестирования блока
    • connection_fields — значения полей подключения

Пример ответа:

{
    "uuid": "a1db9946-2454-423f-a76e-fd8a6e815f97",
    "data": {
        "batch_size": 10,
    }
 }

Где

  • uuid — идентификатор запроса
  • batch_size — количество записей в запросе разработки итераций

Обработка итераций

При обработке итераций входные данные приходят в виде набора входных полей с учетом примененного маппинга. Типы входных полей предположительно известны на стороне Python — отсюда возвращалось их описание.

Конвертация типов значений определяется соглашением о типах данных. Значения переменных входных полей передаются в виде вложенных массивов. В последующих пачках данных приходят только значения переменных входных полей.

Пример передаваемой пачки данных:

{
    "uuid": "e3128e7c-26f5-494c-8beb-3ad96c470310",
    "cmd": "insert",
    "data": {
        "dynamic_field_values": [[
            "Строка1",
            9.99,
            {"Name":"Иван","Values":[1723717500,1725971582,1599741185]},
            [1, 2],
            "file_contents/4xXmZtu0zjuYxVQOnIZH.tmp"
        ],[
            "Строка2",
            8.88,
            {"Name":"Анна","Values":[1747678746,1724876374,1587798799]},
            [3, 4],
            "file_contents/vyquY2sx7mfTw2omCzk0oLB.tmp"
        ]],
        "end_of_data": true
    }
}

Где

  • uuid — уникальный идентификатор запроса
  • cmd — команда вставки данных
  • data — объект с вставляемыми данными
  • dynamic_field_values — массив записей для вставки
  • end_of_data — флаг (true), указывающий на последнюю пачку данных для вставки

Ответ на первую пачку данных:

{
    "uuid": "dcbce17f-3606-4f0a-bba3-26f196512b2d",
    "data": {
        "aggregate_mode": true,
        "output_variables": [{
            "type": "FileContent",
            "name":"File1"
        },{
            "type": "Long",
            "name":"Long1"

        } ,{
            "type": "Object",
            "name":"var_2",
            "struct": [{
                "name": "field1",
                "type": "UnixTime"
            },{
                "name": "field2",
                "type": "Long"
            }]
        },{
            "type": "ObjectArray",
            "name": "var3",
            "struct": [{
                "name": "field1",
                "type": "Object",
                "struct": [{
                    "name": "field1_1",
                    "type": "BigIntegerArray"
                }]
            },{
                "name": "field2",
                "type": "String"
            }]
        }],
        "records": [[ #ответ на первую запись [
            "/file_contents/77YRlI4CB6u2mj4ARVuB.tmp",
            101,
            {
                "field1":1735035524,
                "Field2":1234512
            },
            [{
                "field1":{
                    "field1_1": [3243243254324324323, 87568758758657865765]
                },
                "field2": "StringValue1"
            }]
        ],[
            "/file_contents/77YRlI4CB6u2mj4ARVuB.tmp",
            102,
            {
                "field1":1735035524,
                "Field2":1234512
            },
            []
        ]],[#ответ на вторую запись
        ],[#две пустых записи - агрегация
        ],[#результат агрегации
            "/file_contents/BC2ZD1n8EZ29XrOtjhUq.tmp",
            951,
            {
                "field1":1735031111,
                "Field2":9876541
            },
            [{
                "field1":{
                    "field1_1": [44444444444444444, 55555555555555555555]
                },
                "field2": "StringValue2"
            }]
         ]]
    }
}

Где

  • uuid — уникальный идентификатор запроса
  • data — объект с данными ответа
    • aggregate_mode — режим агрегации. В значении true будет прервана связь с вышестоящими блоками, так как у одной записи несколько источников и невозможно определить корректную ссылку на родительский блок
    • output_variables — описание выходных переменных
      • name — имя поля
      • type — тип поля
    • records — возвращаемые записи. Представляет собой массив трех уровней вложенности:
      • 1-й уровень — каждый элемент соответствует одной входящей записи
      • 2-ой уровень — каждый элемент соответствует одной исходящей записи. Набор элементов представляет собой ответ на входящую запись
      • 3-й уровень — каждый элемент соответствует значению поля исходящей записи. Порядок и типы полей соответствуют описанию в output_variables

Ответ на последующие пачки данных:

{
    "uuid": "9beb4eef-832f-47dd-b828-ebb3edefbae6",
    "data": {
        "records": [[#ответ на первую запись - две выходных записи [
          "file:file_contents/77YRlI4CB6u2mj4ARVuB.tmp",
            101,
                {
                    "field1":1735035524,
                    "Field2":1234512
                },
                [{
                    "field1":{
                    "field1_1": [3243243254324324323, 87568758758657865765]
                },
                "field2": "StringValue1"
            }]
        ],[
            "file:file_contents/77YRlI4CB6u2mj4ARVuB.tmp",
            102,
            {
                "field1":1735035524,
                "Field2":1234512
            },
            []
        ]],[#ответ на вторую запись - пусто
        ],[#две пустых записи - агрегация или фильтрация
        ],[[
            "base64:5W2Jipw4e4kvyquY2sx7mfTw2omCzk0oLBs0F2Z7LF2nDI3wwF6ggbAYRVA5fPKtS0tHdsce9i7aZ73VcWGt2MzLHQTueQ6QYbacrwAoXR0SlKEbR5Tx",
            951,
            {
                "field1":1735031111,
                "Field2":9876541
            },
            [{
                "field1":{
                    "field1_1": [44444444444444444, 55555555555555555555]
                },
                "field2": "StringValue2"
            }]
      ]]]
    }
}

Где

  • uuid — уникальный идентификатор запроса
  • data — объект с данными ответа
    • records — возвращаемые записи. Представляет собой массив трех уровней вложенности:
      • 1-й уровень — каждый элемент соответствует одной входящей записи
      • 2-ой уровень — каждый элемент соответствует одной исходящей записи. Набор элементов представляет собой ответ на входящую запись
      • 3-й уровень — каждый элемент соответствует значению поля исходящей записи. Порядок и типы полей соответствуют описанию в output_variables
Заметка

Чтобы избежать ошибки в результате выполнения запроса, данные должны соответствовать формату output_variables.

Ответ может поддерживать следующие типы данных:

  • Long
  • LongArray
  • Double
  • DoubleArray
  • Boolean
  • BooleanArray
  • String
  • StringArray
  • BigInteger
  • BigIntegerArray
  • BigDecimal
  • BigDecimalArray
  • DateTime
  • DateTimeArray
  • Object
  • ObjectArray
  • FileContent

Базовый подход предполагает использование числовых типов максимального размера: BigInteger и BigDecimal. Если можно гарантировать поставку значений типа меньшего размера, без риска получить ошибку переполнения, можно использовать типы Long и Double — это улучшит производительность.

ObjectArray и Object — сложные типы. Элемент метаданных должен содержать поле "struct", описывающее иерархичную структуру объекта. ObjectArray — всегда массив объектов, поэтому для описания типа его элементов также достаточно поля "struct", описывающего структуру его элемента.

Закрытие сессии

Пример закрытия сессии:

{
    "uuid":"731d5558-f474-4a27-94e0-4008b60ca48d",
    "cmd":"close",
    "data":{}
}

Где

  • uuid — уникальный идентификатор сессии
  • cmd — команда закрытия данных
  • data — пустой объект данных

Пример ответа:

{  
    "uuid":"731d5558-f474-4a27-94e0-4008b60ca48d"
}

Где uuid — уникальный идентификатор запроса.

Логирование

{
    "cmd": "log",
    "data": {
        "level": "INFO",
        "text": "Received value var_1=123"
    }
}

Где

  • cmd — команда закрытия сессии
  • data — пустой объект данных

Идентификатор запроса не требуется — ответ не ожидается и не обрабатывается (по принципу fire-and-forget).

Список уровней логирования:

  • ERROR
  • WARN
  • INFO
  • DEBUG
  • TRACE

Обработка ошибок

В ответ на любой запрос можно вернуть ошибку.

{
    "uuid":"f6a820f5-34c4-4c23-bb51-2bffa26d9898",
    "cmd": "error",
    "data": {
        "code": "unknown_error",
        "text": "Непредвиденная ошибка",
        "params": [{
            "name": "file",
            "value": "vkK8Og2BNyPnJ15wp5Mc.tmp"
        }]
    }
}

Где

  • uuid — уникальный идентификатор запроса
  • cmd — команда ошибки
  • data — объект данных
    • code — код ошибки
    • text — текст сообщения
    • params — параметры ошибки
      • name — имя параметра
      • value — значение параметра

Была ли статья полезна?

Да
Нет
Предыдущая
Пример создания пользовательской интеграции
Следующая
Python SDK
8 (800) 555-89-028 (495) 150-31-45team@infomaximum.com
Для бизнеса
support@infomaximum.com
Компания
© 2010–2025. ООО «Инфомаксимум»
Мы используем файлы cookies, чтобы сайт был лучше для вас.