search string side menu

Модули расширения системы > Пользовательские модули / Методы API в модулях

Методы API в модулях

В ELMA365 авторы модулей могут создавать свои собственные методы и использовать их в web API, в сценариях виджетов, страниц и процессов или при настройке шаблона документа. Например, можно создать методы для запуска бизнес-процесса, сложной выборки данных или организовать методы для промежуточного взаимодействия с внутренней или внешней системой.

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

Создание метода

Чтобы создать метод, выполните следующие действия:

  1. Перейдите в Администрирование > Модули.
  2. Наведите курсор на модуль и нажмите на появившийся значок шестерёнки.

extention-settings1

  1. Перейдите на вкладку Методы API.
  2. Нажмите Редактировать. Откроется редактор методов.
  3. Нажмите кнопку +Добавить. В открывшемся окне внесите нужную информацию.

exten_16

  • Название* — укажите название метода;
  • Адрес* — в выпадающем списке выберите один или несколько методов HTTP запроса. Доступны следующие методы: GET, POST, PUT, PATCH, DELETE. Укажите адрес, по которому будет доступен метод. В адресе с помощью знака / можно обозначить путь к вложенным методам. Например, /main/email_dispatch. Количество уровней вложенности неограниченно. Путь к методу может заканчиваться знаком /, например, call_events/route/;
  • Функция* — создайте функцию, которая будет выполняться при получении запроса;
  • Авторизация — выберите тип авторизации, который будет применяться при получении запроса:
    • Внутренняя авторизация — метод можно вызывать только внутри модуля, например, в других методах, виджетах, действиях в бизнес-процессах, обработчиках событий с помощью команды Namespace.api.название_метода. Подробнее об этом мы написали ниже. Пользователь, от имени которого исполняется сценарий, должен быть авторизован в ELMA365;
    • Внешняя авторизация — при выборе этой опции метод будет доступен из внешней системы по токену;
  • Асинхронный запуск — опция позволяет продолжить работу, не дожидаясь окончания выполнения метода;
  • Описание — укажите подробное описание метода.
  1. Перейдите на вкладку Сценарии и напишите метод. Для этого используется язык программирования TypeScript. Более подробно про принципы написания сценариев в ELMA365 читайте в справке ELMA365 TS SDK.
  2. Сохраните и опубликуйте метод.

Доступ к глобальным константам

При написании методов можно использовать константу Global. Она даёт доступ к переменным, содержащимся в разделах, и к глобальным параметрам. Использование этого объекта препятствует дальнейшей выгрузке модуля. То есть, если использовать константу Global для написания метода API, то этот модуль с этим методом нельзя будет экспортировать.

Чтобы разрешить доступ к константе Global:

  1. В редакторе методов перейдите на вкладку Сценарии.

exten-17

  1. В верхнем меню нажмите Настройки.
  2. В открывшемся окне выберите опцию Global.

Использование файлов в сценариях

В сценариях модуля вы можете использовать изображения, шаблоны документов, инструкции и т. д. Для этого в редакторе методов перейдите на вкладку Файлы и загрузите необходимый документ.

exten-18

Откройте файл в режиме просмотра и скопируйте его идентификатор в URL-адресе страницы. С помощью идентификатора вы можете обратиться к загруженному файлу в любых сценариях модуля.

Серверные зависимости

В ELMA365 On-Premises вы можете добавлять на вкладке Файлы npm-пакеты с серверными зависимостями. Подробнее об этом читайте в статье «Серверные зависимости пакетов npm».

Вызов метода API из кода сценария

После создания метода API в модуле вы можете вызвать его в любом сценарии этого модуля. Для этого в глобальной переменной Namespace есть свойство api:

let response = await Namespace.api.some_method.call({
    method: "POST",
    headers: {
        "X-My-CutomHeader": "Some header data"
    },
    query: {
        "skip": "0",
        "take": "10"
    },
    body: "Any body here"
});

В этот метод передаётся тип FetchRequest, он же используется в методе fetch.

При вызове этого метода происходит веб-вызов метода API через стандартный протокол HTTP. Поэтому ответ от метода приходит в виде стандартного объекта FetchResponse.

Также для разработки модулей с вебхуками можно получить адрес метода API с помощью команды Namespace.api.some_method.getUrl(), которая вернёт строку с полным адресом этого метода для дальнейшего вызова. Этот метод бывает полезен, когда во время работы сторонний сервис требует указать обратный адрес для вызова.

Служебные заголовки

В методах API в каждом объекте запроса, который передаётся в сценарий, содержатся заголовки, хранящие информацию о вызванном методе:

  • :method — http-метод;
  • :path — часть URL-адреса метода, которая приводится после домена, вместе с query-параметрами, например, /test1/test2?q=12345&n=aaa;
  • :scheme — используемый в методе протокол: http или https;
  • :authority — домен и порт (кроме 80 и 443), с которого пришёл запрос, например, elma365.ru или local.elma365.dev:4200.
extention-widegets.html extention-activities.html