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

Сергей Гусев
28.04.2025
Статья посвящена общим вопросам включения, настройки и использованию 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 или какое-либо действие в системе.

Рис.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 на странице «Управление протоколами».
Может возникнуть ситуация, когда вам в СЭО 3KL понадобится отключить веб-службы. При этом следует помнить: если ранее была установлена опция «Включить веб-службы для мобильных устройств» — необходимо сначала снять ее и только после этого появится возможность снять опцию «Включить веб-службы».

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

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

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

// Укажите свой домен вместо 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. Управление зачислением на курсы через глобальные группы

Возможности, описанные в данном разделе, доступны в СЭО 3KL, начиная с версии 4.1.17a и реализуются при помощи плагина, local_ws_enrolcohort.

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

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

Основным преимуществом предложенного ниже решения является отсутствие необходимости выполнять какие-либо доработки на стороне СЭО 3KL. Данный алгоритм может быть рекомендован для реализации практически любой внешней автоматизации.

Задача:
Используя web-сервисы, реализовать возможность массового создания в СЭО 3KL курсов на основании подготовленного csv-файла. При этом, во вновь созданных курсах должно быть изначально преднастроено несколько способов зачисления «Синхронизация с глобальной группой» для возможности автоматического зачисления участников существующих в системе глобальных групп. Роль (слушатель, преподаватель, ассистент и т. п.), с которой пользователь зачисляется на курс, заранее известна и определяется принадлежностью к глобальной группе.

Предусловия:
1) Предполагается, что csv-файл с параметрами создаваемых в СЭО 3KL курсов уже подготовлен и содержит в себе все необходимые для реализации решения данные.
2) Аккаунты сервиса Google (drive и collab) создан и активен, все необходимые параметры доступа и настройки выполнены на компьютере ответственного за создание курсов сотрудника организации (в нашем примере - диспетчера-администратора СЭО 3KL).

Применение сервисов Google не является обязательным условием решения. Вы можете использовать любые иные облачные хранилища и платформы для создания и выполнения кода на Python.

Общий алгоритм решения (Рис. 4.5.1):
1) Диспетчер администратор загружает csv-файл в облачное хранилище (или вносит необходимые правки в ранее выгруженный, непосредственно в таблице хранилища).
2) Загружает скрипт в облачную среду разработки (Google Collab, в нашем примере), указывает путь до csv-файла.
3) Запускает скрипт.
4) Мреда разработки выполняет скрипт: отправляет к API СЭО 3KL запросы, получает информацию по участвующим сущностям, передает информацию по создаваемым курсам, экземплярам способов записи на курсы и конкретным записям пользователей на курсы.
5) СЭО 3KL создает указанные в csv-файле курсы, способов записи на курсы.
6) СЭО 3KL зачисляет пользователей глобальных групп в созданные курсы согласно определенным в настройках способов подписки параметрам.

Рис. 4.5.1. Структурная схема решения.

Пример скрипта на Python:

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}')

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

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

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