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

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;
}

Рекомендации по настройке веб-службы и формированию запроса

1 шаг – Включение веб-служб и протоколов

Перед настройкой веб-службы нужно включить функционал веб-служб в СЭО 3KL на странице администрирования «Расширенные возможности».

При вызове функции local_ws_enrolcohort_add_instance в указанном курсе создается способ зачисления «Синхронизация с глобальной группой». Выполнение функции аналогично созданию способа зачисления на курс «Синхронизация с глобальной группой» через интерфейс системы.

2 шаг – Создание пользователя для веб-службы

Далее необходимо настроить для роли, которой будет обладать пользователь, выполняющий запрос через веб-службу, права, необходимые для выполнения этого запроса.

Права, необходимые для использования функций плагина local_ws_enrolcohort, можно посмотреть в интерфейсе списка веб-служб, расположенном по пути: Администрирование -> Сервер -> Веб-службы -> Внешние службы (Рис. 4.5.1.а).

На этой странице необходимо нажать на ссылку «Функции» в строке с плагином local_ws_enrolcohort (см. поз. 1 Рис 4.5.1.а). Откроется страница со списком необходимых прав для функций плагина (Рис. 4.5.1.б).

Для функции local_ws_enrolcohort_add_instance необходимы следующие права (см. поз. 1 Рис. 4.5.1.б):

• moodle/cohort:view: Просматривать глобальные группы сайта;
• moodle/role:assign: Добавлять и удалять членов глобальной группы;
• moodle/course:managegroups: Управлять группами;
• moodle/course:enrolconfig: Настраивать способы записи на отдельные курсы;
• enrol/cohort:config: Настраивать экземпляры способа записи на курс «Синхронизация с глобальной группой».

Пользователю веб-службы должна быть назначена какая-либо глобальная роль, у которой будут возможности назначать другие роли пользователям в СЭО 3KL. В приведенном далее примере это глобальная роль «Управляющий».

Для пользователя веб-службы (глобальная роль «Управляющий») необходимо указать роли, которые он может назначать. Для этого на странице, расположенной по пути: Администрирование -> Пользователи -> Права -> Определить роли (Рис. 4.5.1.в) нужно перейти во вкладку «Разрешить назначение ролей» (поз. 1 Рис. 4.5.1.в) и отметить в левом столбце таблицы, какие роли может назначать пользователь веб-службы (глобальная роль «Управляющий») (поз. 2 Рис. 4.5.1.в). 

При определении функции local_ws_enrolcohort есть обязательные параметры, без которых функция не будет отрабатывать, а также необязательные параметры, которые позволяют персонализировать работу функции.

3 шаг – при формировании запроса необходимо использовать следующие параметры:

Таблица 4.5.1.а. Параметры функции local_ws_enrolcohort.

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

4.5.2. Получение информации о способах записи на курс через глобальные группы

Пример запроса 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. сервис зачисления на курс по глобальной группе (local_ws_enrolcohort)">Редактирование способа записи на курс через глобальную группу

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

Пример скрипта на 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}')

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