¶ Интеграция с LMS через сервис GC Bridge
Это позволит отправлять оценки в LMS, не реализуя при этом поддержку протокола LTI или API этих LMS на своей стороне. На данный момент поддерживается только интеграция по протоколу LTI 1.1, но и её достаточно, чтобы отправлять оценки в задания в SmartLMS, Coursera и т.д.
Документация к API находится тут - https://constructor.auditory.ru/bridge/docs.
¶ 0. Получение токена для доступа к API
Написать в канал проекта 588 и попросить токен, желательно указать проект 
Токен -- строка вида d970f0df4c6f9d56032df54241ffaaf (hexadecimal, то есть a-f и циферки) длиной от 40 символов, максимальная длина останется тайной.
Токен обязательно нужно держать в секрете, поскольку с его помощью можно как минимум отправлять оценки для заданий, созданных в системе вашим грейдером.
Его нужно передавать с каждым запросом к API (это эндпойнты, которые начинаются с /api, ваш капитан) в хедере Authorization с типом Bearer (дружно передаём привет OAuth 2.0). Вот так:
Authorization: Bearer d970f0df4c6f9d56032df54241ffaaf
¶ 1. Создание "задания" (assignment)
Представляет собой привязку задания в вашем сервисе к конкретному способу интеграции. Допустим, на вашей стороне преподаватель создает задание, и указывает, что требуется интеграция с LMS. Тогда после создания задания на вашей стороне, нужно создать задание (assignment) в системе GC Bridge.
Для этого нужно отправить POST-запрос на эндпойнт /api/v1/assignments, в теле отправить JSON следущего вида:
{
"source_id": "string",
"title": "string",
"description": "string",
"return_user_data": false,
"type": "LTI_1p0",
"url": "string"
}
source_id нужен на тот случай, если вы хотите сохранить информацию про ID задания у вас в системе, если это не требуется, можно оставить null.
title, description - название и описание задания, пока что нигде не фигурируют. Можно оставить null.
type - тип интеграции, на данный момент поддерживается только LTI_1p0, что соответствует интеграции по протоколу LTI 1.1.
url - URL задания (универсальный для всех студентов). Ожидается, что студент, перейдя по этой ссылке, попадет на свой личный вариант задания, или на какую-то общую страницу для этого задания (например, в Google Classroom, если у грейдера нет интерфейса или нет возможности перенаправить студента на его личный вариант/задания). Обязательный параметр и здесь обязательно должен быть URL. Отправить просто какую-то строку нельзя. Отправлять относительные пути тоже нельзя. Только полные URL. Можно использовать кастомные схемы (например, tg://whatever).
return_user_data - передавать ли токен с информацией о пользователе при переходе из LMS в задание. В случае с true пользователю будет показана промежуточная страница, где нужно будет нажать на кнопку (так надо - ограничения протокола HTTP и современных браузеров). После нажатия пользователь попадет на нужный адрес с POST-запросом, в теле которого в параметре user_data будет находиться JWT-токен с даными о пользователе. Формат следующий:
{
"iat": 1612359332,
"exp": 1612445732,
"iss": "GCBridge",
"sub": "iiivanov@edu.hse.ru",
"user_email": "iiivanov@edu.hse.ru",
"user_is_instructor": false,
"user_is_student": true,
"user_full_name": "Иван Иванов"
}
Токен нужно проверить с помощью алгоритма RS256 (обязательно ограничьте список доступных для проверки алгоритмов!) при помощи любой библиотеки для работы с JWT при помощи данного публичного ключа.
В ответ придет информация о созданной интеграции такого вида:
{
"source_id": "string",
"title": "string",
"description": "string",
"return_user_data": false,
"type": "LTI_1p0",
"url": "string",
"provider_id": 0,
"consumer_key": "string",
"shared_secret": "string",
"created_at": "2021-05-12T18:11:45.047Z",
"updated_at": "2021-05-12T18:11:45.047Z",
"id": 0
}
Первые шесть полей описаны выше, provider_id - ID вашего грейдера, created_at/updated_at - без комментариев.
Интерес представляют следующие поля:
id - ID задания/привязки в сервисе GC Bridge. По-хорошему, нужно сохранить где-то рядом с данными о созданном у вас в грейдере задании, потому что он нужен как минимум для отправки оценок.
consumer_key, shared_secret - длинные или не очень секретные (!) ключи, которые нужно передать преподавателю под названиями Consumer Key и Shared Secret соответственно. Они используются для добавления задания в LMS.
Можно не хранить это все у себя, а запрашивать при необходимости по Assignment ID, отправив GET на /api/v1/assignments/{assignment_id}. Или получив список всех заданий - GET на /api/v1/assignments
Примечание: задания чужих грейдеров вы со своим токеном получить не сможете, как и отправить оценку в чужое задание (думаю, вполне понятно, почему), но нумерация у них общая.
¶ 2. Передача данных преподавателю для добавления задания в LMS
При создании задания в LMS преподавателю нужны данные о том, с чем, собственно, и как интегрироваться.
Версия LTI - 1.1 (если доступно несколько, нужно выбрать именно её).
Tool URL для интеграции по LTI 1.1 - https://constructor.auditory.ru/bridge/lti/1p0/launch.
Consumer Key и Shared Secret - соответственно, consumer_key и shared_secret.
Указанные выше поля почти во всех LMS так и называются.
Преподаватель должен обязательно разрешить передачу E-Mail адресов студентов в настройках задания в LMS.
¶ Примерчик для Moodle (SmartLMS тоже по сути Moodle)
Для проверки работы интеграции можно воспользоваться официальной демо-версией Moodle (сбрасывается каждый час) - https://sandbox.moodledemo.net. Её же и будем использовать в примере.
Заходим от имени преподавателя.
Получаем задание с ключами.
Добавляем задание с LTI в LMS.
В настройках задания в пункте, где нужно указать Tool, жмем на плюсик (добавить новый).
Указываем название, описание, версию LTI (1.1), Tool URL из этой инструкции, а так же наши Consumer Key и Shared Secret. Желательно сделать так, чтобы задание открывалось в новой вкладке (new window), потому что иначе оно откроется в виде блока iframe прямо на странице с заданием в LMS.
Указываем, что LMS необходимо делиться с нами E-Mail'ами студентов.
Видим, что LTI Tool добавился, продолжаем настраивать задание. Вводим название.
Здесь тоже нужно разрешить всё, если вдруг что-то не разрешено.
Вводим максимальную оценку за задание.
И делаем так, чтобы оно помечалось как выполненное только когда придёт оценка от грейдера через нас.
Сохраняем наши труды.
И видим только что созданное задание в курсе.
Готово! Теперь при клике на задание студент сразу же переадресуется через нас на URL, который указал грейдер. Ну и оценки возвращаются сюда же, само собой разумеется.
¶ 3. Переход студентов из LMS
После создания задания в LMS, студенты перед выполнением задания обязательно должны перейти в задание из LMS. Именно оттуда. И именно перейти, а не скопировать ссылку и перейти в обход, вставив её в адресную строку или ещё миллионом способов. По этой причине не рекомендуется передавать преподавателям прямые ссылки на задание, если оно с интеграцией по LTI (если у вас сейчас вдруг так делается).
Тут нужно указать немного технических деталей, чтобы было понятно, почему так. При передаче оценки обратно в LMS по протоколу LTI, LMS всё равно, что мы теоретически знаем E-Mail пользователя. Протокол LTI такое не умеет. Оценка из GC Bridge (это уже происходит незаметно от вас) должна передаваться в LMS исключительно с указанием ID результата, который ранее LMS должна передать в GC Bridge при переходе студента из задания с LTI в LMS. Соответственно, если студент не откроет задание в LMS и не перейдет через наш сервис на задание в вашем грейдере, LMS не передаст нам ID результата и оценку вы отправить не сможете. Печаль. Копирование ссылок из LMS, если вдруг какая-то LMS зачем-то дает так делать, не работает, потому что пользователь должен придти в GC Bridge с POST-запросом на эту ссылку со всеми данными. Ссылка даже приведена выше, она для всех общая и никакой полезной информации в ней не будет, если её просто скопируют и перейдут. Вот-с.
После открытия задания через LMS, студента тут же через нас переадресует на url, который вы указывали, когда создавали задание в GC Bridge. Задание определяется по Consumer Key, поэтому преподавателю дополнительно никаких параметров у задания указывать не нужно. Привет, Stepik.
¶ 4. Отправка оценки
После того, как студент выполнил (или не выполнил) задание, нужно отправить его оценку.
Для этого нужно обязательно перевести её в интервал 0.0-1.0 и отправить со следующим POST-запросом на /api/v1/assignments/{assignment_id}/grades:
{
"grade": 0.78,
"user_email": "user@example.com"
}
Где grade - оценка, приведенная к интервалу 0.0-1.0 (если что, реальный интервал для оценки указывает преподаватель в LMS, а это как бы своеобразные проценты от макс. балла, установленного там преподавателем), user_email - почта студента.
Почту студента нужно указывать в том виде, в котором студент известен в LMS. К сожалению, пока что магия с угадыванием, должно там быть @edu.hse.ru или @miem.hse.ru, у нас не работает.
В ответ вам вернется или результат отправки оценки в LMS вида:
{
"tc_response": "string",
"grade": 0.78
}
Где tc_response - ответ LMS, должен быть success в случае, если все получилось, другие возможные значения - failure, processing, unsupported. Если вернулось что-то, кроме success, уже возможно, что проблема не на вашей или нашей стороне, а на стороне LMS, но во всяком случае запрос до неё дошёл и она что-то ответила.
Другие возможные исходы - 404 с описанием, что не так, 502, 422. 404 может возвращаться, если вы отправили оценку для человека, который ни разу не переходил в задание из LMS, или если вы передали не ту почту (ну или если ID задания неверный, но это уже такое). 502 возвращается, если не удалось достучаться до LMS с нашей стороны (проблема может быть и у нас, и на стороне LMS). 422 - неверный формат запроса (забыли сконвертировать оценку или ещё куча возможных ошибок валидации).
В этой инструкции скорее расписано, что есть что, все точные форматы запросов и почти точные (за исключением ошибок) форматы ответов есть в документации к API. Там же можно нажать на кнопку Authorize, вставить туда токен и тестить запросы.