Инструменты WEB API в СЭО 3КL. Возможности и примеры

Сергей Гусев
10.22.24
Статья посвящена общим вопросам включения, настройки и использованию API для интеграции СЭО 3КL с внешними системами.
Применение материалов, изложенных в статье, требует наличия специальных знаний. . .

1. Общая информация

Одним из вариантом взаимодействия внешних систем с СЭО 3КL является программный интерфейс приложений (API) - набор определенных способов и правил, позволяющий различным программным продуктам обмениваться данными по стандартизированным протоколам. API СЭО 3КL поддерживает обмен данными по протоколам REST, SOAP и XML-RPC.

Клиент API (непосредственно внешняя система или пользователь API через веб-браузер/консоль) обращается с запросом к серверу СЭО 3КL на выполнение функции (метода) API (Рис. 1.1). В зависимости от исполняемой функции, результатом запроса будет получение от сервера ответа с информацией из СЭО 3КL или какое-либо действие в системе.

Рис.1.1. Пример схемы работы WEB API.

Перед обработкой запроса выполняется аутентификация клиента API — сервер должен знать, кто делает запросы и имеет ли он на это право. Для этого запрос отправляется вместе с ключом безопасности (токеном), который сгенерирован с использованием информации учетной записи пользователя API. Если запрос содержит валидный ключ, то сервер выполнит его обработку.

Инструкции о том, как правильно использовать API (формировать запрос), информация о классах и типах возвращаемых значений, примеры запроса и сообщения об ошибке, как правило, доступны в документации API.

Общий алгоритм использования метода API может выглядеть следующим образом:

  • подготовка к использованию API:
    • настройка веб-службы;
    • подготовка пользователя для веб-службы и настройка его прав;
    • генерация ключа безопасности (токена) веб-службы.
  • использование API:
    • создание запроса;
    • отправка запроса;
    • получение и обработка ответа.

-Вернуться к содержанию-

2. Возможности

2.1. Документация API СЭО 3КL

Полный перечень функций (методов), которые могут быть использованы при интеграции по API доступны в интерфейсе СЭО 3КL на странице «Документация API» (Администрирование->Сервер->Веб-службы->Документация API) (Рис. 2.2.1).

Рис. 2.2.1. Внешний вид страницы «Документация API».

Перечень методов выводится в алфавитном порядке. Название методов стандартизировано и формируется как
компонент_имя_метода (например, core_user_create_users), где

компонент — область применения метода (core_user),
имя_метода — выполняемое действие (create_users).

При клике на выбранном методе раскроется документация по нему, которая содержит (Рис. 2.2.2):

Рис. 2.2.2. Пример документации по методу «core_user_create_users».
  • Краткое описание метода (см. поз. 1 Рис. 2.2.2).
  • Требуемые для функции аргументы (см. поз. 2 Рис. 2.2.2).
  • Описание структуры с указанием переменных, их типов и передаваемых данных (параметров) (см. поз. 3 Рис. 2.2.2).
  • Вид ответа на запрос (см. поз. 4 Рис. 2.2.2).
  • Вид сообщения об ошибке (см. поз. 5 Рис. 2.2.2).
  • Дополнительная информация (см. поз. 6 Рис. 2.2.2).

-Вернуться к содержанию-

2.2. Использование API на примере создания нового пользователя (протокол REST)

Администратор настраивает СЭО 3КL для работы с веб-службами.

Администратор использует метод API core_user_create_users и, следуя документации API, формирует curl-запрос к серверу СЭО 3КL:

curl -k --location 'https://your_lms/webservice/rest/server.php' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'moodlewsrestformat=json' \
--data-urlencode 'wsfunction=core_user_create_users' \
--data-urlencode 'wstoken=your_token' \
--data-urlencode 'users[0][username]=testtestuser' \
--data-urlencode 'users[0][createpassword]=1' \
--data-urlencode 'users[0][firstname]=Иван' \
--data-urlencode 'users[0][lastname]=Иванов' \
--data-urlencode 'users[0][email]=testtestuser@test.dev' \
--data-urlencode 'users[0][customfields][0][type]=mentor' \
--data-urlencode 'users[0][customfields][0][value]=195'

в котором:

your_lms — название системы дистанционного обучения в которой работает администратор;
core_user_create_users — имя вызываемого метода API;
your_token — ключ безопасности настроенной веб-службы;
testtestuser — логин создаваемого пользователя;
[createpassword]=1 — указание на генерацию пароля системой;
Иван — имя создаваемого пользователя;
Иванов — фамилия создаваемого пользователя;
testtestuser@test.dev — электронная почта создаваемого пользователя;
[customfields][0][type]=mentor и [customfields][0][value]=195 — указание на создание дополнительного поля профиля типа mentor и присвоение ему значения 195.

В результате в СЭО СЭО 3КL создается пользователь с указанным в запросе логином, именем и фамилией. При этом, в соответствии с параметрами запроса, пароль для входа был автоматически сгенерирован системой и отправлен ему на электронную почту.

-Вернуться к содержанию-

3. Предварительная настройка СЭО 3КLтребуются права администратора

Действия в данной инструкции с пометкой требуются права администратора могут быть выполнены только при наличии доступа «Полный Администратор». Начиная с 2022 года для вновь заключаемых договоров такой набор прав предоставляется роли «Диспетчер-администратор» по умолчанию. Если ваш договор был заключен раньше, вы можете обратиться в техподдержку с соответствующей заявкой на расширение набора прав диспетчера-администратора.
Важно! Неосторожные действия полного администратора могут повредить систему и контент таким образом, что исправление последствий вмешательства выйдет за рамки гарантийной технической поддержки. В случае внесения правок в глобальные настройки рекомендуем вам полностью убедиться в том, что вы понимаете, за что отвечают данные настройки. Если у вас возникают сомнения в назначении глобальных настроек, обратитесь за помощью в техническую поддержку.
Подробная информация в статье «Полный административный доступ».

Для использования методов API, необходимо создать и настроить в СЭО 3КL веб-службу. Общая последовательность действий и ссылки на соответствующие интерфейсы настроек доступны на странице «Обзор» (Администрирование->Сервер->Веб-службы->Обзор) (Рис. 3.1).

Рис. 3.1. Страница «Веб-службы».

-Вернуться к содержанию-

3.1. Включение веб-служб и протоколов

Функционал веб-служб включается на странице администрирования «Расширенные возможности» (Рис. 3.1.1).

Рис. 3.1.1. Настройка «Включить веб-службы» на странице администрирования «Расширенные возможности».

После того, как были включены веб-службы, необходимо убедиться, что на странице «Управление протоколами» (Администрирование->Сервер->Веб-службы->Управление протоколами) включены только те протоколы API, которые будут использоваться (Рис. 3.1.2). Те протоколы, которые не планируется использовать, рекомендуется отключить.

Рис. 3.1.2. Включенный протокол REST на странице «Управление протоколами».

-Вернуться к содержанию-

3.2. Создание пользователя для веб-службы

В СЭО 3КL должен быть создан специальный пользователь (далее - пользователь интеграции), от имени которого будет происходить взаимодействие со внешней системой (Администрирование->Пользователи->Учетные записи->Добавить пользователя->). Затем пользователю выдаются необходимые права — шаги «3. Создать специального пользователя», «4. Проверить права пользователя» и «7. Выбрать определенного пользователя» процедуры настройки (см. Рис. 2.1).

В целях безопасности, настоятельно рекомендуем создать для такого пользователя в СЭО 3КL отдельную роль и определить в этой роли минимально необходимый для корректной работы интеграции набор прав: право на использование протокола + все те права, которые необходимы для каждой функции создаваемой веб-службы.
Дополнительная информация о создании и настройке ролей в статье «Определение ролей, настройка прав».

-Вернуться к содержанию-

3.3. Создание веб-службы

В CЭО 3КL создается новая веб-служба (Администрирование->Сервер->Веб-службы->Внешние службы->кнопка «Добавить»), в которую включаются все необходимые для планируемой интеграции функции (Рис. 2.4) — шаги «5. Выбрать службу» и «6. Добавить функции» процедуры настройки (см. Рис. 2.1).

Рис. 2.4. Добавление функций в ранее созданную веб-службу «Test_api_kbz».

-Вернуться к содержанию-

3.4. Создание ключа безопасности (токена)

Для ранее созданного пользователя интеграции на странице «Создать ключ» (Администрирование->Сервер->Веб-службы->Управление ключами->кнопка «Создать ключ») генерируется ключ безопасности (токен), при помощи которого скрипт интеграции будет получать доступ к веб-службе (Рис. 2.5, Рис. 2.6).

Рис. 2.5. Пример генерации токена пользователю интеграции Апиаев Прохор для веб-службы «Test_api_kbz».

Рис. 2.6. Сгенерированный ключ безопасности на странице «Управление ключами».
Если пользователю интеграции может потребоваться доступ к документации используемых в веб-службе функций, необходимо дополнительно включить опцию «Документация веб-служб» (шаг «9. Включить информацию для разработчиков» процедуры настройки). Ссылки на документацию станут ему доступны на странице «Ключи безопасности».

-Вернуться к содержанию-

4. Решения

4.1. Создание пользователей, соответствующих заданным параметрам

Протокол, название метода: REST, core_user_create_users

Интерфейс СЭО 3КL, в котором доступен результат: https://your_lms/admin/user.php

Текст запроса:

<?php
// Укажите свой домен вместо YOUR_DOMAIN
$wsurl = 'https://YOUR_DOMAIN/webservice/rest/server.php';
// Список аргументов, передаваемых в запросе по API
$arguments = [];
// Укажите свой токен
$arguments['wstoken'] = 'YOUR_TOKEN';
// Формат - json
$arguments['moodlewsrestformat'] = 'json';
// функция создания пользователей
$arguments['wsfunction'] = 'core_user_create_users';
// список создаваемых пользователей
$arguments['users'] = [
// данные о первом и единственном в данном примере пользователе, который будет создан
[
// Логин
'username' => 'apidemo',
// Имя
'firstname' => 'Api',
// Фамилия
'lastname' => 'Demo',
// Адрес электронной почты
'email' => 'api@demo.dev',
// Флаг для автоматической генерации пароля
'createpassword' => 1,
// Подразделение
'department' => 'DemoDep',
],
];
$ch = curl_init($wsurl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($arguments, '', '&'));
// При отладке на сервере с самоподписанным сертификатом используйте (раскомментируйте) следующие две опции
// curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
// curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
$response = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($response === false) {
echo 'Curl error: ' . curl_error($ch) . PHP_EOL;
} else {
echo 'Http code: ' . $httpcode . PHP_EOL;
echo 'Response: ' . json_encode(json_decode($response, true), JSON_PRETTY_PRINT|JSON_UNESCAPED_UNICODE) . PHP_EOL;
}

-Вернуться к содержанию-

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

Протокол, название метода: REST, block_dof_storage_persons_get_bu

Интерфейс СЭО 3КL, в котором доступен результат: https://your_lms/blocks/dof/im/persons/list.php

Текст запроса:

<?php
// Укажите свой домен вместо YOUR_DOMAIN
$wsurl = 'https://YOUR_DOMAIN/webservice/rest/server.php';
// Список аргументов, передаваемых в запросе по API
$arguments = [];
// Укажите свой токен
$arguments['wstoken'] = 'YOUR_TOKEN';
// Формат - json
$arguments['moodlewsrestformat'] = 'json';
// функция получения персоны деканата по идентификатору пользователя системы
$arguments['wsfunction'] = 'block_dof_storage_persons_get_bu';
// Идентификатор пользователя
$arguments['userid'] = 190;
// Флаг, создавать ли персону в деканате, если для найденного пользователя системы персоны еще нет
$arguments['create'] = true;
$ch = curl_init($wsurl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($arguments, '', '&'));
// При отладке на сервере с самоподписанным сертификатом используйте (раскомментируйте) следующие две опции
// curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
// curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
$response = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($response === false) {
echo 'Curl error: ' . curl_error($ch) . PHP_EOL;
} else {
echo 'Http code: ' . $httpcode . PHP_EOL;
echo 'Response: ' . json_encode(json_decode($response, true), JSON_PRETTY_PRINT|JSON_UNESCAPED_UNICODE) . PHP_EOL;
}

-Вернуться к содержанию-

4.3. Создание в портфолио ЭД достижений по шаблону типа Настраиваемый

Протокол, название метода: REST, block_dof_storage_achievementins_create

Интерфейс СЭО 3КL, в котором доступен результат: https://your_lms/blocks/dof/im/achievements/my.php?departmentid=your_department_id&limitnum=30&personid=your_person_id

Текст запроса:

<?php
// Укажите свой домен вместо YOUR_DOMAIN
$wsurl = 'https://YOUR_DOMAIN/webservice/rest/server.php';
// Список аргументов, передаваемых в запросе по API
$arguments = [];
// Укажите свой токен
$arguments['wstoken'] = 'YOUR_TOKEN';
// Формат - json
$arguments['moodlewsrestformat'] = 'json';
// функция создания в портфолио ЭД достижений по шаблону типа Настраиваемый
$arguments['wsfunction'] = 'block_dof_storage_achievementins_create';
// Список достижений
$arguments['achievementins'] = [
// первое и единственное в данном примере добавляемое достижение
[
// идентификатор шаблона достижений
'achievementid' => 15,
// идентификатор персоны
'personid' => 103,
// данные достижения (список критериев и их значений)
'data' => [
(object)[
// номер критерия
'criterianum' => 0,
// значение критерия
'criteriavalue' => 'Достижение',
],
(object)[
// номер критерия
'criterianum' => 1,
// значение критерия
'criteriavalue' => strtotime('+10 days'),
],
(object)[
// номер критерия
'criterianum' => 2,
// значение критерия
'criteriavalue' => 1,
],
],
]
];
$ch = curl_init($wsurl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($arguments, '', '&'));
// При отладке на сервере с самоподписанным сертификатом используйте (раскомментируйте) следующие две опции
// curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
// curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
$response = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($response === false) {
echo 'Curl error: ' . curl_error($ch) . PHP_EOL;
} else {
echo 'Http code: ' . $httpcode . PHP_EOL;
echo 'Response: ' . json_encode(json_decode($response, true), JSON_PRETTY_PRINT|JSON_UNESCAPED_UNICODE) . PHP_EOL;
}

-Вернуться к содержанию-

4.4. Создание и редактирование настроек критериев завершения курса

Протокол, название метода: REST, local_opentechnololgy_edit_completion_criteria

Интерфейс СЭО 3КL, в котором доступен результат: https://your_lms/course/completion.php?id=your_course_id

Текст запроса:

<?php
// Укажите свой домен вместо YOUR_DOMAIN
$wsurl = 'https://YOUR_DOMAIN/webservice/rest/server.php';
// Список аргументов, передаваемых в запросе по API
$arguments = [];
// Укажите свой токен
$arguments['wstoken'] = 'YOUR_TOKEN';
// Формат - json
$arguments['moodlewsrestformat'] = 'json';
// функция создания в портфолио ЭД достижений по шаблону типа Настраиваемый
$arguments['wsfunction'] = 'local_opentechnololgy_edit_completion_criteria';
// Список курсов с критериями достижений
$arguments['courses'] = [
// первый и единственный в данном примере курс с критериями
[
// идентификатор курса
'id' => 81,
// разблокировать настройки (удалить данные о выполнении критериев выполнения курса)
'settingsunlock' => 1,
// общее - курс завершен, когда ЛЮБОЕ из условий будет выполнено
'overall_aggregation' => 2,
// выполнение элемента курса
'criteria_activity' => [
// объект со сведениями по элементу курса
(object)[
// идентификатор модуля курса
'cmid' => 1761,
// флаг - включен ли модуль курса в критерий выполнения
'value' => 1
],
],
// Требуемое условие - ЛЮБОЙ из выбранных элементов курса должен быть выполнен
'activity_aggregation' => 2,
// Завершение других курсов
'criteria_course' => [
// объект со сведениями о курсе
(object)[
// идентификатор курса
'courseid' => 16
],
],
// Требуемое условие - ЛЮБОЙ из выбранных курсов должен быть завершен
'course_aggregation' => 2,
// Дата - включить
'criteria_date' => 1,
// Дата, когда курс будет помечен как завершенный (в формате unix timestamp). В примере - через 10 дней от сегодняшнего дня.
'criteria_date_value' => strtotime('+10 days'),
// Продолжительность зачисления - включить
'criteria_duration' => 1,
// Пользователь должен оставаться зачисленным на протяжении (в секундах). В примере - 10 дней.
'criteria_duration_days' => 10 * 24 * 60 * 60,
// Оценка за курс - включить
'criteria_grade' => 1,
// Необходимая оценка курса
'criteria_grade_value' => floatval(50.00000),
// завершение вручную за другого
'criteria_role' => [
// объект роли
(object)[
// идентификатор роли
'roleid' => 3
],
],
// Требуемое условие - ЛЮБАЯ из выбранных ролей может поставить отметку выполнения
'role_aggregation' => 2,
// Пользователь может сам поставить отметку о выполнении - включить
'criteria_self' => 1,
// исключение из курса - включить
'criteria_unenrol' => 1,
]
];
$ch = curl_init($wsurl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($arguments, '', '&'));
// При отладке на сервере с самоподписанным сертификатом используйте (раскомментируйте) следующие две опции
// curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
// curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
$response = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($response === false) {
echo 'Curl error: ' . curl_error($ch) . PHP_EOL;
} else {
echo 'Http code: ' . $httpcode . PHP_EOL;
echo 'Response: ' . json_encode(json_decode($response, true), JSON_PRETTY_PRINT|JSON_UNESCAPED_UNICODE) . PHP_EOL;
}

-Вернуться к содержанию-

Рейтинг ответа: 5 (1 оценка)

Комментарии запрещены