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. Сохраните и опубликуйте метод.

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

По умолчанию в методах API можно обращаться только к компонентам модуля, на уровне которого они настраиваются. Вы можете дополнительно получить доступ к другим объектам системы через глобальные константы. Для этого в редакторе методов перейдите на вкладку Сценарии и на верхней панели нажмите Настройки.

exten-17

Вы можете использовать опции:

  • Глобальные константы — установите флажок напротив опции Global, чтобы получить возможность обращаться к объектам из всех разделов системы и к глобальным параметрам. Для этого применяется константа Global;

начало внимание

При использовании константы Global для написания метода API модуль с этим методом нельзя экспортировать.

конец внимание

  • Опциональные зависимости (доступны в объекте Imports) — выберите разделы или пользовательские модули и установите с ними опциональные зависимости. После этого в сценариях к ним можно обращаться через константу Imports. При использовании опциональных зависимостей модуль можно экспортировать без ограничений.

Чтобы создать зависимость, нажмите + Добавить раздел и выберите компонент системы. Затем в колонке Псевдоним задайте для него уникальное имя, которое будет использоваться в сценарии. Допустимы латинские буквы и цифры, для разделения слов можно использовать знак подчёркивания. По умолчанию используется код раздела или ID модуля.

начало внимание

Опциональные зависимости и константа Imports по умолчанию доступны в поставке SaaS, а также On‑Premises, начиная с версии системы 2024.2. В более ранних версиях администратору системы нужно включить фича-флаг allowScriptImportsDependencies. Подробнее об этом читайте в статьях «Изменение параметров On-Premises Enterprise» и «Изменение параметров On-Premises Standard».

конец внимание

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

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

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 из сторонней системы

Метод API в модуле можно вызвать из стороннего сервиса. Для этого в веб-запросе указывается прямая ссылка на созданный метод в виде полного URL-адреса.

Чтобы получить ссылку, откройте страницу управления модулем и перейдите на вкладку Методы API. Напротив названия метода нажмите на значок копирования URL-адреса.

extention-api-5

Если при создании метода выбрана опция внешней авторизации, в запросе используется заголовок Authorization и указывается индивидуальный токен пользователя. Подробнее об этом читайте в справке по публичному API ELMA365.

Пример вызова метода API в модуле через команду fetch:

let response = await fetch('https://abcd1234.elma365.ru/api/extensions/f1e6cf15-7c65-4be5-8443-021a280dcd80/script/upload', {
    method: "POST",
    headers: {
        "Authorization": "Bearer " + secureToken
    },
    query: {
        "file_id": fileId
    },
    body: JSON.stringify(uploadBody)
});

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

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

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