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

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

<?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

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

<?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

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

<?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_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

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

<?php
// Укажите свой домен вместо 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;
}

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