Скрипт может обрабатывать параметры запроса, выполнять действия на экземпляре и формировать ответ. В результате настройки REST API создаётся конечная точка для обращений из внешних систем, в том числе с других экземпляров SimpleOne.
Необходимая роль: admin.
Настройка конечной точки
Чтобы настроить конечную точку, выполните следующие шаги:
- Создайте модуль API. Для этого перейдите в Настройки REST API→ Модули API.
Заполните поля Наименование, Активен и Путь.
- Нажмите Сохранить или Сохранить и выйти. После этого в связанном списке Версия API будет создана запись версии API.
Нажмите на созданную запись версии API, чтобы открыть ее. При необходимости в связанном списке можно создать дополнительные записи версии модуля API, например, v2.
Первая версия v1 создается автоматически при создании модуля API.
Запросы API без конкретной версии используют последнюю активную версию модуля.
В связанном списке перейдите Действия API → Создать.
Вы также можете настроить действие API, скрипт которого будет запускаться при запросе к действию.
Запрос к действию может выполняться с указанием версии:
{your_instance_url}/v1/api/{application}/{module_path}/{version}/{action_path}и без указания версии:
{your_instance_url}/v1/api/{application}/{module_path}/{action_path}Запросы API без указания версии используют последнюю активную версию модуля.
Заполните поля Наименование и Путь. Пример значения в поле Путь: tickets-count.
- В поле HTTP-метод, укажите метод для вызова действия.
В поле Скрипт, укажите, какой скрипт необходимо вызвать при REST запросе на действие. Для работы с запросами REST API на платформе SimpleOne созданы классы SimpleRestRequest и SimpleRestResponse. Объекты данных этих классов доступны в скрипте Действие API. Пример:
API action(function (request, response) { const reqBody = request.getBody(); response.setBody({ "body": JSON.stringify(reqBody), "count": 1 }) })(SimpleApiRequest, SimpleApiResponse)- Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.
Вы можете настроить Параметры действия запроса API, связанные с действием. Для каждого параметра можно указать обязательность:
При попытке отправить запрос без обязательного параметра в ответе будет содержаться сообщение вида:{"error":"Required parameter param_1 not sent.","timing":{"before_echo": ...}}
Вызов конечной точки
Для вызова конечной точки используйте следующий формат URL:
https://your_instance_url/v1/api/applicationSlug/module_path/version/action_path?params
где:
- your_instance_url – URL вашего экземпляра;
- applicationSlug – значение поля Слаг того приложения, для которого создается эта конечная точка.
- module_path – значение поля Путь, указанное в модуле API.
- version – значение поля Путь, указанное в версии API.
- action_path – значение поля Путь, указанное в действии API.
- params – параметры GET.
Пример URL для вызова конечной точки:
https://sandbox-01.dev.simpleone.ru/v1/api/c_simple/api_module_path/api_action_path?param_1=value_1
Авторизация
Вы можете отправлять запросы в Scripted REST API при помощи Bearer токена или без авторизации. Тип авторизации запросов зависит от значения флажка Требуется аутентификация на форме Действие API.
Запрос на действие API, не требующий авторизации (Требуется аутентификация =Нет), выполняется под пользователем Guest User::
Запросы с недействительными Bearer токенами также выполняются под пользователем Guest User.
Для Basic Auth авторизации запросов к Scripted REST API выполните следующие шаги:
- Настройте отправку POST запроса /v1/auth/login с Basic Auth из внешней системы на экземпляр для получения токена.
- Настройте отправку запроса к Scripted REST API с полученным токеном.
Схема авторизации:
Пример серверного скрипта с использованием Simple API для получения токена через POST запрос с авторизацией Basic Auth:
const simpleInstanceUri = ss.getProperty('simple.instance.uri');
const URL_BASE = (simpleInstanceUri.startsWith('https://')) ? simpleInstanceUri : `https://${simpleInstanceUri}`;
const authRequest = sws.restRequestV1();
authRequest.setRequestUrl(`${URL_BASE}/v1/auth/login`);
authRequest.setRequestMethod('POST');
authRequest.setRequestHeader('Content-type', 'application/json');
const payload = {
"username": "admin",
"password": "qwerty123456"
}
authRequest.setRequestBody(JSON.stringify(payload));
const authResponse = authRequest.execute();
if (JSON.parse(authResponse.getBody()).status === 'ERROR') {
ss.error(JSON.parse(authResponse.getBody()).errors[0].message);
ss.info('Check credentials at 10..11 lines of current script');
return;
}
ss.info(JSON.parse(authResponse.getBody()).data.auth_key);
// Инфо: 5WvOT9Ejlxd6Gb8bkCWMtG3XXMYcoDDJ
Поддерживаемые типы Content-Type
Для получения тела запроса в скрипте API действия вызывайте метод getBody() для объекта request.
Ниже представлен пример тестового скрипта для API действия:
(function (request, response) {
const reqBody = request.getBody();
const bodyForResponse = typeof reqBody === 'string' ? reqBody : JSON.stringify(reqBody);
response.setBody({
"request_body_type": typeof reqBody,
"request_body": bodyForResponse
})
})(SimpleApiRequest, SimpleApiResponse)
Используйте следующие типы Content-Type types для запросов, отправляемых на API действие:
- application/json
- application/jsonp
- application/xml
- text/xml
- text/html
- text/plain
Отправка POST запроса с телом в виде JSON
Отправка POST запроса с телом в виде XML
Отправка POST запроса с телом в виде HTML
Отправка POST запроса с телом в виде текста
Ответ API действия
Чтобы сформировать ответ действия API, используйте объект response:
response.setBody({
"count": 100,
"status": "OK",
"error_message": ""
})
В ответ действия API включен ключ timing со значением времени выполнения скрипта API действия:
"timing": {
"before_echo": 0.0884089469909668
}
