Главная

Cоздание пользовательской интеграцииBETA

Эта статья поможет вам создать первую интеграцию с использованием NodeJS и Package-cli. Здесь показано, как шаг за шагом создать пользовательскую интеграцию, настроить подключение к внешнему сервису и использовать ее в сценарии автоматизации.

Установка NodeJS

Для работы с интеграциями потребуется NodeJS. Ниже приведены инструкции для Ubuntu и Windows.

Чтобы установть NodeJS на ОС Ubuntu выполните следующие команды:

sudo apt update
sudo apt install nodejs

Чтобы установть NodeJS на ОС Windows выполните следующие команды:

Заметка

Версия NodeJS приведена в качестве примера. При использовании команды замените указанную версию на ту, которую вы устанавливаете.

powershell -c "irm https://community.chocolatey.org/install.ps1|iex"
choco install nodejs --version="24.13.0"

После установки убедитесь, что NodeJS установлен корректно:

node -v

Инициализация репозитория интеграции

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

Заметка

Если git-репозиторий уже существует в директории, он будет переинициализирован.
Вместо my_integration можно указать ., тогда проект интеграции создастся в текущей директории.

npx @infomaximum/package-cli integration init my_integration

Где my_integration — имя создаваемой директории, в которой инициализирован проект интеграции.

Создание первого блока и подключения

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

export const getAllScripts: IntegrationBlock<
  { onlyActive: boolean },
  ICommonAuthData
> = {
  label: "Получить все скрипты в системе",
  description: "Блок получает все скрипты в системе",
  inputFields: [
    {
      key: "onlyActive",
      type: "boolean",
      label: "Только активные скрипты",
      default: true,
    },
  ],
  executePagination: (service, bundle, _context) => {
    if (!bundle.authData || !bundle.authData.url) {
      service.stringError("Отсутствует подключение.");
    }
    const explorer = new GraphQLClient(service);
    const response = explorer.query<IApiResponse>(
      bundle.authData.url,
      `query {
        automation {
          script {
            script_general_list {
              items {
                element {
                  id
                  name
                  enabled
                }
              }
            }
          }
        }
      }`
    );

    const items = response.data?.automation.script.script_general_list.items ?? [];

    const output = items.reduce<TNormalizedItem[]>((acc, { element }) => {
      if (element.name.includes("_DISABLE_")) {
        return acc;
      }

      if (bundle.inputData.onlyActive && !element.enabled) {
        return acc;
      }

      acc.push([element.id, element.name, element.enabled]);
      return acc;
    }, []);

    const outputVariables: OutputBlockVariables[] = [
      { type: "Long", name: "id" },
      { type: "String", name: "name" },
      { type: "Boolean", name: "enabled" },
    ];

    return {
      output,
      output_variables: outputVariables,
      state: undefined,
      hasNext: false,
    };
  }
}

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

import { IntegrationConnection } from "@infomaximum/integration-sdk";
import { ICommonAuthData } from "../types/connections";

export const basicConnect: IntegrationConnection<ICommonAuthData> = {
  label: "Подключение по ApiKey",
  description: "Подключение по ApiKey",
  inputFields: [
    {
      key: "connection_apiKey",
      type: "text",
      label: "API-ключ",
    },
    {
      key: "connection_host",
      type: "text",
      label: "Хост",
    },
    {
      key: "connection_port",
      type: "text",
      label: "Порт ",
    },
    {
      key: "host_button",
      type: "button",
      label: "Автоопределение хоста",
      typeOptions: {
        saveFields: (service, bundle) => {
          const preparedHost = bundle.authData.BASE_URL.replace(
            /^https?:\/\//,
            ""
          ).replace("/webhook/" + bundle.authData.GUID, "");

          const [host, port = ""] = preparedHost.split(":");

          return {
            connection_host: host,
            connection_port: port,
          };
        },
      },
    },
  ],
  execute: (service, bundle) => {
    function createUrl(host: string, port: string, apiKey: string): string {
      const hasProtocol = /^https?:\/\//.test(host);
      const base = hasProtocol ? host : `http://${host}`;

      if (!port || port === "0") {
        return `${base}/graphql?api_key=${apiKey}`;
      }
      return `${base}:${port}/graphql?api_key=${apiKey}`;
    }

    return {
      apiKey: bundle.authData.connection_apiKey,
      host: bundle.authData.connection_host,
      port: bundle.authData.connection_port,
      url: createUrl(
        bundle.authData.connection_host,
        bundle.authData.connection_port,
        bundle.authData.connection_apiKey
      ),
    };
  },
  refresh: () => {
    /*Empty*/
  },
};

Добавления блока и подключения в структуру интеграции

Файл index.ts является точкой входа пользовательской интеграции. В нем собираются все блоки и подключения. На основе этого файла формируется объект интеграции.

Пример файла index.ts:

import { basicConnect } from "./connections/connections";
import { getAllScripts } from "./modules/scripts/getAllScripts";

app = {
  schema: 2,
  version: "3.0.0",
  label: "Proceset",
  description: "",
  blocks: { getAllScripts },
  connections: { basicConnect },
};

Где:

blocks — это список действий, доступных в интеграции
connections — список подключений, через которые блоки будут взаимодействовать с внешними системами

Сборка интеграции

Чтобы запустить сборку скрипта интеграции с последующим отслеживанием изменений в файлах и автоматической пересборкой выполните следующую команду:

Заметка

После выполнения команды сборка будет распоолжена в папке build.

yarn dev

Добавление интеграции в Proceset

Подробный порядок добавления интеграции в пространство описан в инструкции.

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

Да

Нет

Использование объектов интеграции

Python-блоки в модуле автоматизации