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

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

В настройках пользовательского модуля доступно два способа применения методов:

• через скрипты — метод создаётся и выполняется в системе. Можно создать функции общего назначения и использовать их повторно в разных процессах и виджетах модуля;
• через делегирование — метод выполняется в переносимом сервисе или внешней платформе. Делегирование методов позволяет использовать возможности стороннего ресурса, не ограничиваясь инструментами, доступными в скриптах ELMA365. В модуле настраивается адрес, по которому можно обращаться к такому методу.

Важно: в поставке ELMA365 On‑Premises делегированные методы API поддерживаются с версии 2025.10. Модуль с такими методами нельзя импортировать в более ранние версии системы.

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

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

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

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

• Название* — укажите название метода;
• Адрес* — в выпадающем списке выберите один или несколько методов HTTP‑запроса. Доступны следующие методы: GET, POST, PUT, PATCH, DELETE. Затем укажите адрес, по которому будет доступен метод API. При этом вы можете:
  • обозначить путь к вложенным методам — с помощью знака / задайте дочерний метод, например main/email_dispatch или call_events/route/. Количество уровней вложенности неограниченно;
  • задать гибкий адрес для передачи значений переменных в URL метода — добавьте в конце адреса метода сочетание символов /*, например orders/* или orders/process/*. В скрипте метода вы сможете настроить обработку значений переменных, которые передаются при его вызове. Например, можно передавать ID пользователя, чтобы получить в результате запроса его имя и электронную почту. Подробнее о написании скрипта таких методов и их вызове читайте в статье «Настройка метода API с гибким адресом в модуле».

Обратите внимание, символы / и * в конце адреса не обеспечивают уникальность метода, поэтому адреса двух методов не могут отличаться только ими. Например, если вы уже добавили метод files/, при попытке создать метод files/* возникнет ошибка;

• Тип — выберите тип метода:
  • Скрипт — метод API создаётся и выполняется в ELMA365. Подробнее о его добавлении читайте в разделе «Настройка метода типа „Скрипт“»;
  • Делегированный — используется, когда метод реализован в переносимом сервисе или внешнем ресурсе. В ELMA365 настраивается адрес, на который перенаправляется запрос при вызове метода. Подробнее о том, как это сделать, читайте в разделе «Настройка делегированного метода»;
• Авторизация — выберите тип авторизации, который будет применяться при получении запроса:
  • Внутренняя авторизация — метод можно вызывать только внутри модуля, например, в других методах, виджетах, действиях в бизнес-процессах, обработчиках событий с помощью конструкции Namespace.api.название_метода. Подробнее об этом читайте в разделе «Вызов метода API из кода скрипта». Пользователь, от имени которого исполняется скрипт, должен быть авторизован в ELMA365;
  • Внешняя авторизация — при выборе этой опции метод будет доступен из внешней системы по токену;
  • Нет — метод доступен без авторизации;
• Асинхронный запуск — опция позволяет не ожидать выполнение скрипта метода перед тем, как начать обработку других вызовов в модуле. В этом случае ответ на запрос приходит сразу и не содержит результатов работы метода;
• Описание — укажите подробное описание метода.

6. Сохраните и опубликуйте метод.

Настройка метода типа «Скрипт»

Чтобы добавить скрипт метода API:

1. В поле Функция* создайте функцию, которая будет выполняться при получении запроса. Для этого введите название и нажмите Сохранить.
2. Перейдите на вкладку Скрипты и напишите метод. Для этого в поле Функция* нажмите кнопку Открыть. Метод создаётся на языке программирования TypeScript. Более подробно про принципы написания скриптов в ELMA365 читайте в справке ELMA365 TS SDK.
3. Вернитесь на форму создания метода, чтобы заполнить оставшиеся поля и сохранить настройки.

Настройка делегированного метода

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

Чтобы настроить этот тип метода, заполните поля:

• Делегировать в — выберите, где выполняется метод при его вызове: Переносимый сервис или Внешний http сервис;
• Переносимый сервис* — укажите один из переносимых сервисов модуля, в котором реализуется метод;
• Адрес сервиса* — при делегировании метода во внешний сервис укажите URL‑адрес стороннего ресурса одним из способов:
  • в строковом представлении, например https://example.com/api;
  • с помощью шаблона адреса. Для этого предварительно создаётся переменная в настройках модуля. Это делает управление делегированным методом более гибким. Адрес заполняется на странице подключения модуля без перехода в его настройки;
• Переназначение адреса — укажите путь, по которому делегируемый метод доступен на стороне переносимого или внешнего сервиса. Если он совпадает с адресом метода, оставьте поле пустым.

Затем определите тип авторизации, необходимость асинхронного запуска, а также добавьте описание. Подробнее про эти настройки читайте в разделе «Создание метода».

Шаблон адреса внешнего сервиса

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

Чтобы использовать шаблон адреса внешнего сервиса:

1. В модуле с делегированным методом перейдите на вкладку Настройки и создайте свойство типа Строка.
2. Перейдите на вкладку Методы API и откройте делегированный метод, который перенаправляется во внешний сервис.
3. В поле Адрес сервиса* нажмите значок {+} и выберите созданное ранее свойство типа Строка.
4. Сохраните внесённые изменения и опубликуйте метод.

Теперь пользователи могут заполнять и изменять адрес внешнего сервиса на странице подключения модуля.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Трассировка методов API

Если для метода API включён сбор трейсов в разделе Администрирование > Инструменты разработчика, вы можете проанализировать выполнение его скрипта. Это позволяет оценить продолжительность отдельных запросов, оптимизировать код и выявить причины ошибок.

Чтобы изучить трейсы, в настройках модуля перейдите на вкладку Методы API. Для просмотра записей:

• по всем методам в модуле — в правом верхнем углу страницы нажмите Посмотреть трассировку;
• по определённому методу — нажмите напротив него значок .

Подробнее о настройке трассировки и информации в карточке трейса читайте в статье «Трассировка серверных скриптов».

Вызов метода 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"
});

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

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

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

Вызов метода API из сторонней системы

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

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

Если при создании метода выбрана опция внешней авторизации, в запросе используется заголовок 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 встречается несколько стоящих подряд символов /, они интерпретируются как один.

конец примечание

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

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

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

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

Спасибо за ваш отзыв!

×

Ваш отзыв успешно отправлен!

Спасибо за обратную связь.

×

Уточните, почему:

Рекомендации не помоглиТекст трудно понятьНет ответа на мой вопросСодержание статьи не соответствует заголовкуДругая причина

×

Расскажите, что вам не понравилось в статье:

ДаНет

Выберите вариантРекомендации не помоглиТекст трудно понятьНет ответа на мой вопросСодержание статьи не соответствует заголовкуДругая причина