Инструменты 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_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);

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