Инструменты WEB API в СЭО 3КL. Возможности и примеры
1. Общая информация
2. Возможности
2.1. Документация API СЭО 3КL
2.2. Использование API на примере создания нового пользователя (протокол REST)
3. Предварительная настройка СЭО 3КL
3.1. Включение веб-служб и протоколов
3.2. Создание пользователя для веб-службы
3.3. Создание веб-службы
3.4. Создание ключа безопасности (токена)
4. Решения
4.1. Создание пользователей, соответствующих заданным параметрам
4.2. Получение персоны деканата по идентификатору пользователя системы
4.3. Создание в портфолио ЭД достижений по шаблону типа Настраиваемый
4.4. Создание и редактирование настроек критериев завершения курса
1. Общая информация
Одним из вариантом взаимодействия внешних систем с СЭО 3КL является программный интерфейс приложений (API) - набор определенных способов и правил, позволяющий различным программным продуктам обмениваться данными по стандартизированным протоколам. API СЭО 3КL поддерживает обмен данными по протоколам REST, SOAP и XML-RPC.
Клиент API (непосредственно внешняя система или пользователь API через веб-браузер/консоль) обращается с запросом к серверу СЭО 3КL на выполнение функции (метода) API (Рис. 1.1). В зависимости от исполняемой функции, результатом запроса будет получение от сервера ответа с информацией из СЭО 3КL или какое-либо действие в системе.
Перед обработкой запроса выполняется аутентификация клиента API — сервер должен знать, кто делает запросы и имеет ли он на это право. Для этого запрос отправляется вместе с ключом безопасности (токеном), который сгенерирован с использованием информации учетной записи пользователя API. Если запрос содержит валидный ключ, то сервер выполнит его обработку.
Инструкции о том, как правильно использовать API (формировать запрос), информация о классах и типах возвращаемых значений, примеры запроса и сообщения об ошибке, как правило, доступны в документации API.
Общий алгоритм использования метода API может выглядеть следующим образом:
- подготовка к использованию API:
- настройка веб-службы;
- подготовка пользователя для веб-службы и настройка его прав;
- генерация ключа безопасности (токена) веб-службы.
- использование API:
- создание запроса;
- отправка запроса;
- получение и обработка ответа.
2. Возможности
2.1. Документация API СЭО 3КL
Полный перечень функций (методов), которые могут быть использованы при интеграции по API доступны в интерфейсе СЭО 3КL на странице «Документация API» (Администрирование->Сервер->Веб-службы->Документация API) (Рис. 2.2.1).
Перечень методов выводится в алфавитном порядке. Название методов стандартизировано и формируется как
компонент_имя_метода (например, core_user_create_users), где
компонент — область применения метода (core_user),
имя_метода — выполняемое действие (create_users).
При клике на выбранном методе раскроется документация по нему, которая содержит (Рис. 2.2.2):
- Краткое описание метода (см. поз. 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требуются права администратора
Важно! Неосторожные действия полного администратора могут повредить систему и контент таким образом, что исправление последствий вмешательства выйдет за рамки гарантийной технической поддержки. В случае внесения правок в глобальные настройки рекомендуем вам полностью убедиться в том, что вы понимаете, за что отвечают данные настройки. Если у вас возникают сомнения в назначении глобальных настроек, обратитесь за помощью в техническую поддержку.
Подробная информация в статье «Полный административный доступ».
Для использования методов API, необходимо создать и настроить в СЭО 3КL веб-службу. Общая последовательность действий и ссылки на соответствующие интерфейсы настроек доступны на странице «Обзор» (Администрирование->Сервер->Веб-службы->Обзор) (Рис. 3.1).
3.1. Включение веб-служб и протоколов
Функционал веб-служб включается на странице администрирования «Расширенные возможности» (Рис. 3.1.1).
После того, как были включены веб-службы, необходимо убедиться, что на странице «Управление протоколами» (Администрирование->Сервер->Веб-службы->Управление протоколами) включены только те протоколы API, которые будут использоваться (Рис. 3.1.2). Те протоколы, которые не планируется использовать, рекомендуется отключить.
3.2. Создание пользователя для веб-службы
В СЭО 3КL должен быть создан специальный пользователь (далее - пользователь интеграции), от имени которого будет происходить взаимодействие со внешней системой (Администрирование->Пользователи->Учетные записи->Добавить пользователя->). Затем пользователю выдаются необходимые права — шаги «3. Создать специального пользователя», «4. Проверить права пользователя» и «7. Выбрать определенного пользователя» процедуры настройки (см. Рис. 2.1).
3.3. Создание веб-службы
В CЭО 3КL создается новая веб-служба (Администрирование->Сервер->Веб-службы->Внешние службы->кнопка «Добавить»), в которую включаются все необходимые для планируемой интеграции функции (Рис. 2.4) — шаги «5. Выбрать службу» и «6. Добавить функции» процедуры настройки (см. Рис. 2.1).
3.4. Создание ключа безопасности (токена)
Для ранее созданного пользователя интеграции на странице «Создать ключ» (Администрирование->Сервер->Веб-службы->Управление ключами->кнопка «Создать ключ») генерируется ключ безопасности (токен), при помощи которого скрипт интеграции будет получать доступ к веб-службе (Рис. 2.5, Рис. 2.6).
4. Решения
4.1. Создание пользователей, соответствующих заданным параметрам
Протокол, название метода: REST, core_user_get_users
Интерфейс СЭО 3КL, в котором доступен результат: https://your_lms/admin/user.php
Текст запроса:
$url = 'http://your_lms/webservice/rest/server.php';
$data = [
'criteria' => [
'0' => [
'key' => 'id',
'value' => '4'
]
],
'wstoken' => 'your_token',
'wsfunction' => 'core_user_get_users',
'moodlewsrestformat' => 'json'
];
$positionlist = [
'Должность 1',
'Должность 2',
'Должность 3',
'Должность 4',
'Должность 5',
'Должность 6',
'Должность 7',
'Должность 8',
'Должность 9'
];
$departmentlist = [
'Подразделение 1',
'Подразделение 2',
'Подразделение 3',
'Подразделение 4',
'Подразделение 5',
'Подразделение 6',
'Подразделение 7',
'Подразделение 8',
'Подразделение 9'
];
$countrylist = ['RU', 'GB'];
$citylist = ['RU' => 'Москва', 'GB' => 'Лондон'];
for($i = 1; $i < 20; $i++)
{
$country = $countrylist[rand(0,1)];
$users[] = [
'username' => 'username'.$i,
'firstname' => 'firstname'.$i,
'lastname' => 'lastname'.$i,
'email' => 'email'.$i.'@email'.$i.'.dev',
'createpassword' => 1,
'country' => $country,
'city' => $citylist[$country],
'department' => $departmentlist[rand(0, 8)],
'customfields' => [
['type' => 'chiefmail', 'value' => 'chiefmail'.$i.'@chiefmail'.$i.'.dev'],
['type' => 'regiontext', 'value' => 'RU-ALT'],
['type' => 'manager', 'value' => 'qweasdzxc'],
['type' => 'department', 'value' => $departmentlist[rand(0, 8)]],
['type' => 'flagofcreationnewvacancy', 'value' => 1],
['type' => 'positionname', 'value' => $positionlist[rand(0, 8)]]
]
];
}
$i = 133;
$users[] = [
'username' => 'student'.$i,
'firstname' => 'student'.$i,
'lastname' => 'student'.$i,
'email' => 'student'.$i.'@student'.$i.'.dev',
'password' => 'student'.$i.'Q!1'
];
$data = [
'users' => $users,
'wstoken' => 'your_token',
'wsfunction' => 'core_user_create_users',
'moodlewsrestformat' => 'json'
];
$response = $obj->curl_request($url, $data);
var_dump($response);
4.2. Получение персоны деканата по идентификатору пользователя системы
Протокол, название метода: REST, block_dof_storage_persons_get_bu
Интерфейс СЭО 3КL, в котором доступен результат: https://your_lms/blocks/dof/im/persons/list.php
Текст запроса:
$url = 'http://your_lms/webservice/rest/server.php';// Указать свой домен
$wstoken = 'your_token';// Указать свой токен
$data = [
'userid' => 190,
'create' => true,
'wstoken' => $wstoken,
'wsfunction' => 'block_dof_storage_persons_get_bu',
'moodlewsrestformat' => 'json'
];
$response = $obj->curl_request($url, $data);
var_dump($response);
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
Текст запроса:
$url = 'http://your_lms/webservice/rest/server.php';// Указать свой домен
$wstoken = 'your_token';// Указать свой токен
$criteria0 = new stdClass();
$criteria0->criterianum = 0;
$criteria0->criteriavalue = 'Достижение';
$criteria1 = new stdClass();
$criteria1->criterianum = 1;
$criteria1->criteriavalue = strtotime('+10 days');
$criteria2 = new stdClass();
$criteria2->criterianum = 2;
$criteria2->criteriavalue = 1;
$achievementins = [
[
'achievementid' => 56,
'personid' => 103,
'data' => [$criteria0, $criteria1, $criteria2],
]
];
$data = [
'achievementins' => $achievementins,
'wstoken' => $wstoken,
'wsfunction' => 'block_dof_storage_achievementins_create',
'moodlewsrestformat' => 'json'
];
$response = $obj->curl_request($url, $data);
var_dump($response);
4.4. Создание и редактирование настроек критериев завершения курса
Протокол, название метода: REST, local_opentechnololgy_edit_completion_criteria
Интерфейс СЭО 3КL, в котором доступен результат: https://your_lms/course/completion.php?id=your_course_id
Текст запроса:
$url = 'http://ypur_lms/webservice/rest/server.php';// Указать свой домен
$wstoken = 'your_token';// Указать свой токен
$activity = new stdClass();
$activity->cmid = 1565;
$activity->value = 1;
$course = new stdClass();
$course->courseid = 16;
$role = new stdClass();
$role->roleid = 3;
$courses = [
[
'id' => 81,
'settingsunlock' => 1,
'overall_aggregation' => 2,
'criteria_activity' => [$activity],
'activity_aggregation' => 2,
'criteria_course' => [$course],
'course_aggregation' => 2,
'criteria_date' => 1,
'criteria_date_value' => strtotime('+10 days'),
'criteria_duration' => 1,
'criteria_duration_days' => DAYSECS * 10,
'criteria_grade' => 1,
'criteria_grade_value' => floatval(50.00000),
'criteria_role' => [$role],
'role_aggregation' => 2,
'criteria_self' => 1,
'criteria_unenrol' => 1,
]
];
$data = [
'courses' => $courses,
'wstoken' => $wstoken,
'wsfunction' => 'local_opentechnololgy_edit_completion_criteria',
'moodlewsrestformat' => 'json'
];
$response = $obj->curl_request($url, $data);
var_dump($response);