Инструменты 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. Создание и редактирование настроек критериев завершения курса
4.5. Управление зачислением на курсы через глобальные группы
4.5.1. Создание способа записи на курс через глобальную группу
4.5.2. Получение информации о способах записи на курс через глобальные группы
4.5.3. Редактирование способа записи на курс через глобальную группу
4.5.4. Удаление способа записи на курс по глобальную группу
4.6. Пример внешней автоматизации массового создания курсов с преднастроенными способами зачисления через глобальные группы с использованием скрипта на Python
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_create_users
Интерфейс СЭО 3КL, в котором доступен результат: https://your_lms/admin/user.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
Текст запроса:
// Укажите свой домен вместо 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
Текст запроса:
// Укажите свой домен вместо 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
Текст запроса:
// Укажите свой домен вместо 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;
}
4.5. Управление зачислением на курсы через глобальные группы
4.5.1. Создание способа записи на курс через глобальную группу
Пример запроса curl:
curl -k --location 'https://your_lms/webservice/rest/server.php?wstoken=your_token&wsfunction=local_ws_enrolcohort_add_instance&moodlewsrestformat=json' \ --header 'Content-Type: multipart/form-data' \ --form 'instance[courseid]="81"' \ --form 'instance[cohortid]="14"' \ --form 'instance[roleid]="5"' \ --form 'instance[groupid]="77"' \ --form 'instance[name]="Стажеры"' \ --form 'instance[status]="0"'
Пример запроса php:
$baseurl = 'https://YOUR_DOMAIN/webservice/rest/server.php'; $params['wstoken'] = 'YOUR_TOKEN'; $params['moodlewsrestformat'] = 'json'; $params['wsfunction'] = 'local_ws_enrolcohort_add_instance'; $data['instance[courseid]'] = 81; $data['instance[cohortid]'] = 14; $data['instance[roleid]'] = 5; $data['instance[groupid]'] = 77; // необязательный параметр $data['instance[name]'] = 'Стажеры'; // необязательный параметр $data['instance[status]'] = 0; // необязательный параметр $query = http_build_query($params, '', '&'); $ch = curl_init($baseurl . '?' . $query); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); $response = curl_exec($ch); curl_close($ch); if ($response === false) { echo 'Curl error: ' . curl_error($ch) . PHP_EOL; } else { echo 'Response: ' . json_encode(json_decode($response, true), JSON_PRETTY_PRINT|JSON_UNESCAPED_UNICODE) . PHP_EOL; }
4.5.2. сервис зачисления на курс по глобальной группе (local_ws_enrolcohort)">Получение информации о способах записи на курс через глобальные группы
Пример запроса curl:
curl -k --location 'https://your_lms/webservice/rest/server.php?wstoken=your_token&wsfunction=local_ws_enrolcohort_get_instances&moodlewsrestformat=json' \ --header 'Content-Type: multipart/form-data' \ --form 'course[id]="81"'
Пример запроса php:
<?php $baseurl = 'https://YOUR_DOMAIN/webservice/rest/server.php'; $params['wstoken'] = 'YOUR_TOKEN'; $params['moodlewsrestformat'] = 'json'; $params['wsfunction'] = 'local_ws_enrolcohort_get_instances'; $data['course[id]'] = 81; $query = http_build_query($params, '', '&'); $ch = curl_init($baseurl . '?' . $query); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); $response = curl_exec($ch); curl_close($ch); if ($response === false) { echo 'Curl error: ' . curl_error($ch) . PHP_EOL; } else { echo 'Response: ' . json_encode(json_decode($response, true), JSON_PRETTY_PRINT|JSON_UNESCAPED_UNICODE) . PHP_EOL; }
4.5.3. Редактирование способа записи на курс через глобальную группу
Пример запроса curl:
curl -k --location 'https://your_lms/webservice/rest/server.php?wstoken=your_token&wsfunction=local_ws_enrolcohort_update_instance&moodlewsrestformat=json' \ --header 'Content-Type: multipart/form-data' \ --form 'instance[id]="446"' \ --form 'instance[name]="Московский регион"' \ --form 'instance[roleid]="5"' \ --form 'instance[groupid]="77"' \ --form 'instance[status]="1"'
Пример запроса php:
<?php $baseurl = 'https://YOUR_DOMAIN/webservice/rest/server.php'; $params['wstoken'] = 'YOUR_TOKEN'; $params['moodlewsrestformat'] = 'json'; $params['wsfunction'] = 'local_ws_enrolcohort_update_instance'; $data['instance[id]'] = 446; $data['instance[name]'] = 'Московский регион'; // необязательный параметр $data['instance[status]'] = 1; // необязательный параметр $data['instance[roleid]'] = 5; // необязательный параметр $data['instance[groupid]'] = 77; // необязательный параметр $query = http_build_query($params, '', '&'); $ch = curl_init($baseurl . '?' . $query); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); $response = curl_exec($ch); curl_close($ch); if ($response === false) { echo 'Curl error: ' . curl_error($ch) . PHP_EOL; } else { echo 'Response: ' . json_encode(json_decode($response, true), JSON_PRETTY_PRINT|JSON_UNESCAPED_UNICODE) . PHP_EOL; }
4.5.4. Удаление способа записи на курс через глобальную группу
Пример запроса curl:
curl -k --location 'https://your_lms/webservice/rest/server.php?wstoken=your_token&wsfunction=local_ws_enrolcohort_delete_instance&moodlewsrestformat=json' \ --header 'Content-Type: multipart/form-data' \ --form 'instance[id]="444"'
Пример запроса php:
<?php $baseurl = 'https://YOUR_DOMAIN/webservice/rest/server.php'; $params['wstoken'] = 'YOUR_TOKEN'; $params['moodlewsrestformat'] = 'json'; $params['wsfunction'] = 'local_ws_enrolcohort_delete_instance'; $data['instance[id]'] = 444; $query = http_build_query($params, '', '&'); $ch = curl_init($baseurl . '?' . $query); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); $response = curl_exec($ch); curl_close($ch); if ($response === false) { echo 'Curl error: ' . curl_error($ch) . PHP_EOL; } else { echo 'Response: ' . json_encode(json_decode($response, true), JSON_PRETTY_PRINT|JSON_UNESCAPED_UNICODE) . PHP_EOL; }
4.6. Пример внешней автоматизации массового создания курсов с преднастроенными способами зачисления через глобальные группы с использованием скрипта на Python
Задача:
Используя web-сервисы, реализовать возможность массового создания в СЭО 3KL курсов на основании подготовленного csv-файла. При этом, во вновь созданных курсах должно быть изначально преднастроено несколько способов зачисления «Синхронизация с глобальной группой» для возможности автоматического зачисления участников существующих в системе глобальных групп. Роль (слушатель, преподаватель, ассистент и т. п.), с которой пользователь зачисляется на курс, заранее известна и определяется принадлежностью к глобальной группе.
Предусловия:
1) Предполагается, что csv-файл с параметрами создаваемых в СЭО 3KL курсов уже подготовлен и содержит в себе все необходимые для реализации решения данные.
2) Аккаунты сервиса Google (drive и collab) создан и активен, все необходимые параметры доступа и настройки выполнены на компьютере ответственного за создание курсов сотрудника организации (в нашем примере - диспетчера-администратора СЭО 3KL).
Общий алгоритм решения (Рис. 4.5.1):
1) Диспетчер администратор загружает csv-файл в облачное хранилище (или вносит необходимые правки в ранее выгруженный, непосредственно в таблице хранилища).
2) Загружает скрипт в облачную среду разработки (Google Collab, в нашем примере), указывает путь до csv-файла.
3) Запускает скрипт.
4) Мреда разработки выполняет скрипт: отправляет к API СЭО 3KL запросы, получает информацию по участвующим сущностям, передает информацию по создаваемым курсам, экземплярам способов записи на курсы и конкретным записям пользователей на курсы.
5) СЭО 3KL создает указанные в csv-файле курсы, способов записи на курсы.
6) СЭО 3KL зачисляет пользователей глобальных групп в созданные курсы согласно определенным в настройках способов подписки параметрам.
import requests import pandas as pd from googleapiclient.discovery import build from google_auth_oauthlib.flow import InstalledAppFlow from google.auth.transport.requests import Request # Функция для аутентификации в Google Drive def authenticate_google_drive(): scopes = ['https://www.googleapis.com/auth/drive.readonly'] creds = None if os.path.exists('token.json'): creds = Credentials.from_authorized_user_file('token.json', scopes) # Если нет токена или он просрочен, создаем новый if not creds or not creds.valid: if creds and creds.expired and creds.refresh_token: creds.refresh(Request()) else: flow = InstalledAppFlow.from_client_secrets_file( 'credentials.json', scopes) creds = flow.run_local_server(port=0) # Сохраняем токен для следующего запуска with open('token.json', 'w') as token: token.write(creds.to_json()) return build('drive', 'v3', credentials=creds) # Функция для загрузки файла с Google Drive def download_csv_from_google_drive(drive_service, file_id): request = drive_service.files().get_media(fileId=file_id) fh = io.BytesIO() downloader = MediaIoBaseDownload(fh, request) done = False while done is False: status, done = downloader.next_chunk() print("Download %d%%." % int(status.progress() * 100)) fh.seek(0) df = pd.read_csv(fh) return df # Настройки подключения к Moodle API MOODLE_URL = 'http://your-moodle-site/webservice/rest/server.php' MOODLE_TOKEN = 'your_moodle_webservice_token' # Загрузка CSV-файла с Google Drive drive_service = authenticate_google_drive() csv_data = download_csv_from_google_drive(drive_service, 'your_csv_file_id') min_i = 1 # Минимальное значение i (например, первая строка) max_i = 20 # Максимальное значение i # Проход по строкам CSV-файла for index, row in csv_data.iterrows(): shortname = row['shortname'] categoryid = row['categoryid'] fullname = row['fullname'] summary = row['summary'] cohorts = [] for i in range(min_i, max_i): # Цикл от min_i до max_i включительно cohort_id = row[f'cohort_{i}_id'] # Получаем значение cohort_N_id roleid = row[f'cohort_{i}_roleid'] # Получаем значение cohort_N_roleid cohorts.append({ 'id': cohort_id, 'roleid': roleid }) # Создание курса в Moodle create_course_payload = { 'courses[0][fullname]': fullname, 'courses[0][shortname]': shortname, 'courses[0][categoryid]': categoryid, 'courses[0][summary]': summary, } create_course_response = requests.post(MOODLE_URL, params={'wsfunction': 'core_course_create_courses', 'wstoken': MOODLE_TOKEN, 'moodlewsrestformat': 'json'}, data=create_course_payload) create_course_result = create_course_response.json() course_id = create_course_result['courses'][0]['id'] # Добавление групп в курс for cohort in cohorts: add_cohort_to_course_payload = { 'instance[roleid]': cohort["roleid"], # ID роли студента 'instance[cohortid]': cohort["id"], # ID глобальной группу 'instance[courseid]': course_id # id курса } add_group_to_course_response = requests.post(MOODLE_URL, params={'wsfunction': 'local_ws_enrolcohort_add_instance', 'wstoken': MOODLE_TOKEN, 'moodlewsrestformat': 'json'}, data=add_group_to_course_payload) add_group_to_course_result = add_group_to_course_response.json() print(f'Группа {group} успешно добавлена в курс {course_name}')