Работа с REST-сервисами в системе

Формат адреса для выполнения REST-методов

Формат адреса для выполнения REST-методов:

<URL> + '/services/rest/' + <method> + '?accessKey='+<accessKey>,

где:

  • <URL> — адрес приложения, например, http://127.0.0.1:8080/sd;
  • <method> — часть адреса, идентифицирующая выполняемый метод;
  • <accessKey> — ключ доступа.

Пример. Ссылки для обращения к методам:

http://127.0.0.1:8080/sd/services/rest/create/currency/?accessKey=cd9fd8c6-5d53-49c1-a1b1-706c781d8966&title=Франк&code=frank

http://127.0.0.1:8080/sd/services/rest/create/serviceCall?accessKey=cd9fd8c6-5d53-49c1-a1b1-706c781d8966

Получение базового URL-адреса приложения

Возвращает URL-адрес приложения вида "http://127.0.0.1:8080/sd":

api.rest.getBaseUrl()

Получение ключа для доступа

Для выполнения всех операций требуется ключ доступа (accessKey), под которым будет выполняться операция:

  1. Напишите скрипт и сохраните его в файл getAccessKey.groovy.

    Пример скрипта для пользователя с логином username:

    return api.auth.getAccessKey('username').uuid

  2. Выполните скрипт через консоль приложения SMP, см. Скрипты, выполняемые в консоли.

  3. Запомните результат выполнения скрипта. Полученное значение вводится без пробелов.

    cd9fd8c6-5d53-49c1-a1b1-706c781d8966

Формирование ссылок для доступа к методам

Скриптовое API содержит методы для формирования ссылок, см. Методы API.

При выполнении REST-запросов для пользователя создается активная сессия и он занимает лицензию.
Исключения, методы не занимающие лицензию пользователя: check-status (проверка доступности приложения), /rest-cti/make-call и /rest-cti/cdr/search (методы для интеграции с Asterisk)

Требования для формирования ссылок:

  • Регистр кода параметра должен соответствовать регистру в системе (поиск соответствий регистрозависимый).
  • При создании строки при помощи скрипта и использовании символов кириллицы, кодировка файла и всех символов в нем должна быть UTF-8, иначе в поля будут записаны нечитаемые символы.

  • В строке запроса (URL) запрещена передача ряда символов, поддержка использования которых не соответствует требованиям информационной безопасности (считаются частым источником уязвимостей безопасности):

    • процент — "%" и "%25"
    • закодированная точка (.) — "%2e", "%2E
    • точка с запятой — ";", "%3b", "%3B"
    • закодированный слэш — "%2f", "%2F"
    • двойной слэш — "//", "%2f%2f", "%2f%2F", "%2F%2f", "%2F%2F"
    • двойной обратный слэш — "\\", "%5c", "%5C",
    • NULL-символ — "\0", "%00",
    • символ перевода строки (LF) — "\n", "%0a", "%0A",
    • символ возврата каретки (CR) — "\r", "%0d", "%0D",
    • разделитель строк — "\u2028",
    • разделитель параграфов — "\u2029".

  • Некоторые символы в URL должны быть заменены на аналоги-коды символов (большинство браузеров могут производить это преобразование автоматически):

    • { → %7B
    • } → %7D
    • " → %22

Логирование REST

В консоли логируются все REST-вызовы в формате:

[имя_метода] with args = [параметры вызова метода]

Пример лога:

INFO logging.RestLogger - REST invocation = [edit] with args = [root$101, 40xeyJ0aXRsZSI6IlR1ZSBKYW4gMjkgMTQ6MTM6MTIgWUVLVCAyMDEzIn0=, 6d54ab64-0b7f-47b7-bd53-4ebbe3353add, SecurityContextHolderAwareRequestWrapper[ FirewalledRequest[ org.apache.catalina.connector.RequestFacade@38748d00]]]