edx-api-english.mediawiki

Table of Contents API и интеграция с внешними системами Передача данных пользователей с LMS OpenEdX session_request_callback Параметры прокторинга Необязательные параметры: Обязательные параметры: Инициализация сессии Параметры запроса от EDX к прокторингу: Пример: proctoring_launch_callback Старт экзамена Вызов API: Пример: proctoring_poll_status Опрос статуса Вызов API: Пример: Ответ: Возможные значения статуса: close_exams Завершение экзамена проктором Завершение экзамена Статусы прокторинга Текущий вариант Планируемый вариант user_proctored_exams Запрос всех курсов с proctored экзаменами на которые подписан студент, по username

API и интеграция с внешними системами

API системы должно позволять решение следующих задач:

1. Подключение дополнительных источников данных (ЭКГ, ЭЭГ, окулографическое оборудование)
2. Передачу данных пользователей от внешних систем в систему прокторинга
3. Выгрузку данных сессии прокторинга во внешние системы

Передача данных пользователей с LMS OpenEdX

session_request_callback

Параметры прокторинга

Необязательные параметры:

Имя параметра	Значение
contact_us	ссылка на страницу/форму обратной связи
faq	ссылка на часто задаваемые вопросы
online_proctoring_rules	ссылка на правила прокторинг сервиса
tech_requirements	ссылка на требования к аппаратному/программному обеспечению

Обязательные параметры:

Имя параметра	Значение
crypto_key	ключ шифрования (16 или 24 символа)
exam_register_endpoint	URL по которому EDX запрашивает код прокторинг сессии
exam_sponsor	спонсор прокторинг экзамена
organization	название организации, предоставляющей прокторинг сервис
secret_key	секретный ключ (24 символа)
secret_key_id	ID секретного ключа (возможно, используется для идентификации клиентов на стороне прокторинга)
software_download_url	ссылка для скачивания прокторинг-клиента

Инициализация сессии

Для установления сессии с прокторинг сервисом, EDX генерирует уникальный код экзамена и отсылает его POST запросом вместе с другими данными об экзамене и студенте.

Пример кода экзамена: F5FC0503-278E-48BD-9120-2C91C86BDA8A

Параметры запроса от EDX к прокторингу:

Имя параметра	Значение
examCode	уникальный ключ экзамена EDX
organization	название организации, предоставляющей прокторинг сервис
duration	длительность экзамена по времени (в минутах)
reviewedExam	boolean, всегда false для прокторинг экзамена
reviewerNotes	комбинация Exam Policy (для всех студентов) с исключениями для конкретного студента
examPassword	ключ экзамена EDX зашифрованный с помощью crypto_key (алгоритм шифрования согласовывается с обеих сторон)
examSponsor	спонсор прокторинг экзамена
examName	название экзамена (например Final Exam)
ssiProduct	константа со значением 'rp-now'
examUrl	ссылка на экзамен EDX
orgExtra	дополнительная информация {"examStartDate": dateTime, "examEndDate": dateTime, "noOfStudents": integer, "examID": integer, "courseID": string, "firstName": string, "lastName": string}
orgExtra['examStartDate']	дата и время начала экзамена
orgExtra['examEndDate']	дата и время окончания экзамена
orgExtra['noOfStudents']	количество студентов (всегда 1)
orgExtra['examID']	ID экзамена в базе EDX
orgExtra['courseID']	ID курса (пример: Millionlights/ex12007/2015)
orgExtra['firstName']	имя студента
orgExtra['lastName']	фамилия студента

Пример:

POST api/v1/integration/npoed/

{
    "examCode":"F5FC0503-278E-48BD-9120-2C91C86BDA8A",
    "organization":"ITMO",
    "duration":120,
    "reviewedExam":false,
    "reviewerNotes":"",
    "examPassword":"5bh78-anvjnDG5jjfb#svsAjdvsSd",
    "examSponsor":"",
    "examName":"Final Exam",
    "ssiProduct":'rp-now',
    "examUrl":"https://lms.npoed.org/courses/some_course_id?sdfhsdfhsdjhihnskdjfnkjnkhjdnfhsnkjnh",
    "orgExtra":{
        "examStartDate":"2015-10-10 12:10:34",
        "examEndDate":"2015-10-10 14:10:34",
        "noOfStudents":1,
        "examID":5356,
        "courseID":"some_course_id",
        "firstName":"John",
        "lastName":"Johnson",

    }
}

В ответ EDX ожидает ID сессии (строка/хэш с любым значением), которое будет сохранено и использовано на этапе финализации экзамена.

proctoring_launch_callback

Старт экзамена

После того, как студент завершил идентификацию на прокторинге, прокторинг посылает EDX запрос с кодом экзамена, после чего у студента появляется возможность начать прохождение.

Вызов API:

GET /api/edx_proctoring/proctoring_launch_callback/start_exam/{examCode}

Пример:

GET /api/edx_proctoring/proctoring_launch_callback/start_exam/F5FC0503-278E-48BD-9120-2C91C86BDA8A

Возвращает HTML страницу во встроенный браузер прокторинг приложения. Страница содержит ссылки с правилами использования, FAQ и т.д.

Статус экзамена при этом устанавливается в ready_to_start

proctoring_poll_status

Опрос статуса

После отправки запроса, прокторинг периодически опрашивает статус экзамена EDX и запускает/останавливает сессию (или другие действия) в зависимости от полученного значения.

Вызов API:

GET /api/edx_proctoring/proctoring_poll_status/{examCode}

Пример:

GET /api/edx_proctoring/proctoring_poll_status/F5FC0503-278E-48BD-9120-2C91C86BDA8A

Ответ:

{"status": %status_value%}

Возможные значения статуса:

eligible	the student is eligible to decide if he/she wants to persue credit
created	the attempt record has been created, but the exam has not yet been started
ready_to_start	the attempt is ready to start but requires user to acknowledge that he/she wants to start the exam
started	the student has started the exam and is in the process of completing the exam
ready_to_submit	the student has completed the exam

Статусы ниже рассматриваются в контексте 'completed' состояния

Не допускается изменение значения на указанные выше

declined	the student declined to take the exam as a proctored exam
timed_out	the exam has timed out
submitted	the student has submitted the exam for proctoring review
verified	the exam has been verified and approved
rejected	the exam has been rejected
not_reviewed	the exam was not reviewed
error	the exam is believed to be in error

close_exams

Завершение экзамена проктором

Request:

GET /api/edx_proctoring/v1/proctored_exam/attempt/{exam_code}

Response:

200 OK

Завершение экзамена

Экзамен может завершиться по истечению времени, либо если студент досрочно завершает прохождение.

Прокторинг отслеживает статус. Фактически экзамен завершен при получении статуса submitted. В этом состоянии EDX ожидает от прокторинга данные о ходе экзамена.

При получении статуса submitted прокторинг посылает POST запрос с данными.

Важно: Данные обязательно должны содержать параметр ssiRecordLocator, значением которого является код сессии прокторинга, полученный EDX на первом этапе

Имя параметра	Значение	Тип
examDate	Дата экзамена формат	формат Jul 15 2015 1:13AM
examProcessingStatus	Статус процесса экзамена. (Окончен или нет)	строка
examTakerEmail	Эмеил студента	эмеил
examTakerFirstName	Имя студента	строка
examTakerLastName	Фамилия студента	строка
keySetVersion
examApiData[]	данные идентичные получаемым при инициализации сессии	json массив
overAllComments
reviewStatus	Статус прокторинга. Доступниые значения - 'Clean', 'Rules Violation', 'Not Reviewed', 'Suspicious'	строка
userPhotoBase64String
videoReviewLink	Ссылка на видео ревью	урл
examMetaData	Данные о экзамене	json массив
examMetaData[examCode]	Код экзамена	строка
examMetaData[examName]	Название	строка
examMetaData[examSponsor]	Спонсор	строка
examMetaData[organization]	организация	строка
examMetaData[reviewedExam]	Проревьювеный ли экзамен	"True" или "False"
examMetaData[reviewerNotes]	Заметки ревьювера	строка
examMetaData[simulatedExam]	Симуляция экзамена	"True" или "False"
examMetaData[ssiExamToken]
examMetaData[ssiProduct]
examMetaData[ssiRecordLocator]	ID сессии	строка
desktopComments	Комментарии прокторинга в процессе наблюдения за экраном экзаменуемого	json массив
desktopComments[comments]	Текст комментария	строка
desktopComments[duration]	Продолжительность события	int - минут
desktopComments[eventFinish]	Момент окончания события	int - минута с момента старта экзамена
desktopComments[eventStart]	Момент начала события	in -минута с момента старта экзамена
desktopComments[eventStatus]	Статус события	"Suspicious", "Rules Violation", "Clean"
webCamComments	Комментарии прокторинга в процессе наблюдения за экзаменуемым посредством web-камеры	json массив Содержимое идентично desktopComments

Параметры запроса прокторинга к EDX (пример данных взят от Software Secure, может быть скорректирован под существующие АПИ прокторинга):

{  
   "examDate":"",
   "examProcessingStatus":"Review Completed",
   "examTakerEmail":"",
   "examTakerFirstName":"John",
   "examTakerLastName":"Doe",
   "keySetVersion":"",
   "examApiData":{  
      "duration":exam.duration,
      "examCode":exam.examCode,
      "examName":exam.examName,
      "examPassword":exam.examPassword,
      "examSponsor":exam.examSponsor,
      "examUrl":"http://localhost:8000/api/edx_proctoring/proctoring_launch_callback/start_exam/4d07a01a-1502-422e-b943-93ac04dc6ced",
      "orgExtra":{  
         "courseID":exam.courseId,
         "examEndDate":exam.examEndDate,
         "examID":exam.examId,
         "examStartDate":exam.examStartDate,
         "noOfStudents":exam.noOfStudents
      },
      "organization":exam.organization,
      "reviewedExam":exam.reviewedExam,
      "reviewerNotes":exam.reviewerNotes,
      "ssiProduct":"rp-now"
   },
   "overAllComments":"",
   "reviewStatus":passing_review_status   [  
      0
   ],
   "userPhotoBase64String":"",
   "videoReviewLink":"",
   "examMetaData":{  
      "examCode":request.data.get('attempt_code'),
      "examName":exam.examName,
      "examSponsor":exam.examSponsor,
      "organization":exam.organization,
      "reviewedExam":"True",
      "reviewerNotes":"Closed Book",
      "simulatedExam":"False",
      "ssiExamToken":"",
      "ssiProduct":"rp-now",
      "ssiRecordLocator":exam.generate_key()
   },
   "desktopComments":[  
      {  
         "comments":"Browsing other websites",
         "duration":88,
         "eventFinish":88,
         "eventStart":12,
         "eventStatus":"Suspicious"
      },

   ],
   "webCamComments":[  
      {  
         "comments":"Photo ID not provided",
         "duration":796,
         "eventFinish":796,
         "eventStart":0,
         "eventStatus":"Suspicious"
      }
   ]
}

Статусы прокторинга

Текущий вариант

Статус	Значение	Результат
Clean	No alerts, identification ok	Verified
Rules Violation	Some alerts, identification ok	Verified
Suspicious	Rejected by proctor	Rejected
Not Reviewed	Technical problems; Rejected identification	Rejected

Планируемый вариант

Статус	Значение	Результат
Clean	No alerts, identification ok	Verified
Suspicious	Some alerts, identification ok	Verified
Rules Violation	Rejected by proctor	Rejected
Not Reviewed	Technical problems; Rejected identification	Rejected

user_proctored_exams

Запрос всех курсов с proctored экзаменами на которые подписан студент, по username

Request:

[GET]  http://<EDX_URL>/api/extended/user_proctored_exams/<USERNAME>/

Response:

HTTP 200 OK
Content-Type: application/json
{
    "course-v1:edX+DemoX+Demo_Course": {
        "end": null,
        "name": "edX Demonstration Course",
        "uri": "http://0.0.0.0:8000/api/course_structure/v0/courses/course-v1:edX+DemoX+Demo_Course/",
        "start": "2013-02-05T05:00:00Z",
        "image_url": "/asset-v1:edX+DemoX+Demo_Course+type@asset+block@images_course_image.jpg",
        "exams": [
            {
                "id": 1,
                "course_id": "course-v1:edX+DemoX+Demo_Course",
                "content_id": "block-v1:edX+DemoX+Demo_Course+type@sequential+block@07bc32474380492cb34f76e5f9d9a135",
                "external_id": null,
                "exam_name": "New Subsection",
                "time_limit_mins": 30,
                "is_proctored": true,
                "is_practice_exam": false,
                "is_active": true
            },
            {
                "id": 2,
                "course_id": "course-v1:edX+DemoX+Demo_Course",
                "content_id": "block-v1:edX+DemoX+Demo_Course+type@sequential+block@385f7edb208346fc9d02254aeaae5d33",
                "external_id": null,
                "exam_name": "pr exam",
                "time_limit_mins": 30,
                "is_proctored": true,
                "is_practice_exam": false,
                "is_active": true
            },
        ],
        "id": "course-v1:edX+DemoX+Demo_Course"
    }
}