search string side menu

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

Настройка метода API с гибким адресом в модуле

При вызове метода API в модуле можно передавать в его скрипт значения параметров и обрабатывать их. Например, указывать в URL метода идентификатор файла, который нужно получить, или определять дальнейшие действия в зависимости от переданного значения.

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

Чтобы передавать значения при обращении к методу API:

  • установите для него особый адрес;
  • настройте обработку значений в скрипте метода.

Рассмотрим, как это сделать.

Создание метода с гибким адресом

Допустим, вы создаёте метод API для получения имени и электронной почты сотрудников. При вызове в него передаётся ID пользователя, о котором нужно запросить сведения. Если ID не передан, в ответе отправляются данные всех пользователей.

Чтобы настроить такой метод:

  1. В настройках пользовательского модуля на вкладке Методы API перейдите к редактированию методов.
  2. Нажмите + Добавить.
  3. В открывшемся окне введите название и выберите метод GET, так как при вызове будет происходить получение данных.
  4. В поле Адрес* введите путь к методу и добавьте в конце сочетание символов /*.

api-method-with-wildcard-1

  1. В поле Функция* задайте название функции, содержащей скрипт метода, и нажмите Сохранить.
  2. Сохраните метод API. Теперь часть адреса, которая будет стоять в запросе вместо символа *, не учитывается при маршрутизации. В ней можно передавать параметры.
  3. Перейдите на вкладку Скрипты. Определите, какие действия будут выполняться в методе в зависимости от переданного значения. Для этого получите значение из свойства fragment типа HttpApiRequest, который метод API принимает при вызове:

async function users(req: HttpApiRequest): Promise<HttpResponse | void> {
    const resp = new HttpResponse();
 
    // Запись ID пользователя, полученного при вызове метода, в переменную `userId`
    const userId = req.fragment;
    // Если ID не пустой, выполняется поиск определённого пользователя
    if (userId) {
        const user = await System.users.search().where((f) => f.__id.eq(userId)).first();
        // Если пользователь найден, в ответе передаются его данные
        if (user) {
            resp.status(HttpStatusCode.OK);
            resp.json({
                id: user.data.__id,
                name: user.data.__name,
                email: user.data.email,
            });
        // Если пользователь не найден, в ответе отправляется сообщение об ошибке
        } else {
            resp.status(HttpStatusCode.NOT_FOUND);
            resp.content(`user with id ${ userId } not found`);
        }
        return resp;
    }
 
    // Если в запросе не передан ID, в ответ включаются данные всех пользователей
    const users = await System.users.search().all();
    resp.status(HttpStatusCode.OK);
    resp.json(users.map((user) => ({
        id: user.data.__id,
        name: user.data.__name,
        email: user.data.email,
    })));
 
    return resp;
}

Подробнее о написании скриптов для методов API читайте в статье «Методы API в модулях».

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

Теперь вы можете вызывать настроенный метод API из сторонних систем или из скриптов ELMA365.

Вызов метода с гибким адресом из стороннего сервиса

Обращение к методам API из внешних сервисов выполняется с помощью метода fetch(). В него передаётся полный URL метода API. Чтобы указать в запросе значения параметров, добавьте их в конце адреса через символ /.

Например, при вызове метода users/* передаётся ID пользователя для получения его данных:

let response = await fetch('https://abcd1234.elma365.ru/api/extensions/f1e6cf15-7c65-4be5-8443-021a280dcd80/script/users/fb894dcb-9fe0-4783-b7a9-8a76099446b0', {
    method: "GET",
});

Вызов метода с гибким адресом из скрипта в ELMA365

Для вызова методов API через скрипт применяется метод call().Чтобы передать значения параметров, используйте функцию withFragment().

Например, при вызове метода users/* можно указать ID пользователя, чтобы запросить информацию о нём:

await Namespace.api.users
    .withFragment('fb894dcb-9fe0-4783-b7a9-8a76099446b0')
    .call({
        method: 'GET',
    });

Если передавать параметры не требуется, метод можно вызвать без функции withFragment(). Например, при обращении к методу users/* в этом случае вы получите сведения обо всех сотрудниках:

await Namespace.api.users.call({
    method: 'GET',
});

extention-api.html extention-activities.html