Стандарты API LMS для интеграции надстроек классного журнала OneNote
Область применения: корпоративные записные книжки в Office 365
Этот документ предоставляет вызовы API, необходимые для OneNote для перечисления классов и назначений, установки присвоений, оценок загрузки и обновлений в любой LMS.
Все запросы должны быть аутентифицированы. Все запросы должны выполнятся посредством HTTPS.
Примечание
Мы рекомендуем реализовывать каждую LMS с кодом авторизации для потока в целях реализации oauth2. Это предотвратит неразбериху, связанную с вводом учетных данных пользователя, каждый раз по истечении времени действия маркера доступа.
Поиск и вывод списка классов
Выполнить GET запрос<Specify URL for retrieving list of classes>.
LMS возвращает массив классов JSON для текущего пользователя, прошедшего проверку подлинности.
У каждого класса должны быть следующие свойства:
| Имя свойства | Тип | Описание |
|---|---|---|
| id | строка | Идентификатор для класса, уникальный при установке LMS |
| имя | строка | Удобочитаемое для человека название класса |
Получение списка учащихся в классе
Выполнить GET запрос<Specify URL for retrieving list of students in a class>.
LMS должен возвращать массив JSON учащихся в классе.
Каждый учащийся должен обладать следующими свойствами:
| Имя свойства | Тип | Описание |
|---|---|---|
| id | строка | Идентификатор для класса, уникальный при установке LMS |
| имя | строка | Удобочитаемое имя студента |
| адрес электронной почты | строка | Адрес электронной почты учащегося |
Получение списка заданий для класса
Выполнить GET запрос<Specify URL for retrieving list of assignments for a class>.
LMS должен возвращать массив JSON заданий для класса.
| Имя свойства | Тип | Описание |
|---|---|---|
| id | строка | Идентификатор для класса, уникальный при установке LMS |
| заголовок | строка | Заголовок задания |
| описание | строка | Описание задания |
| gradetypeid | строка | Идентификатор типа класса, уникальный на установке LMS |
| dueDate | дата как строка (формат: 2016-12-25T00: 00: 00) | Срок выполнения задания. LMS не будет хранить или использовать данные о времени. |
| url | строка | URL-адрес задания. Доступно только в поддерживаемых версиях LMS. |
| Необязательное имя свойства | Тип | Описание |
|---|---|---|
| gradetypeid | строка | Идентификатор типа класса, уникальный на установке LMS |
| мин. | целое число | минимальный балл, который может быть присвоен учащемуся |
| макс. | целое число | Максимальный балл, который может быть присвоен учащемуся |
| validgradevalues | список | Действительные значения оценок за это задание |
Назначить задание классу
Выполнить POST запрос<Specify URL for setting an assignment to a class>.
Требуются следующие переменные формы, передаваемой методом POST:
| Имя свойства | Тип | Описание |
|---|---|---|
| заголовок | строка (максимальная длина: 280) | Заголовок задания |
| dueDate | дата как строка (формат: 2016-12-25T00: 00: 00) | Срок выполнения задания |
| описание | строка | Описание задания |
| Необязательное имя свойства | Тип | Описание |
|---|---|---|
| gradetypeid | строка | Идентификатор типа класса, уникальный на установке LMS |
| мин. | целое число | минимальный балл, который может быть присвоен учащемуся |
| макс. | целое число | Максимальный балл, который может быть присвоен учащемуся |
| validgradevalues | список | Действительные значения оценок за это задание |
LMS вернет объект JSON с единственным идентификатором свойства. Значение этого свойства будет идентификатором нового задания.
Получение списка оценок за задание
Выполнить GET запрос<Specify URL for retrieving grades for a given assignment>.
LMS должна вернуть массив JSON учащихся, получивших задание и их оценки/баллы.
Каждый сегмент JSON учащихся должен обладать следующими свойствами:
| Имя свойства | Тип | Описание |
|---|---|---|
| id | строка | Идентификатор для класса, уникальный при установке LMS |
| адрес электронной почты | строка | Адрес электронной почты учащегося |
| С оценкой | логическое значение | Указывает, была ли предоставлена оценка учителем |
| obtainedMark | целое число | Дополнительная оценка, достигнутая учащимся (например, 85) |
| maxMark | целое число | Возможна дополнительная максимальная оценка (например, 100) |
| комментарии | строка | Дополнительная обратная связь с учеником (например, "Отличная работа") |
| оценка | строка | Дополнительный класс, присвоенный учащемуся (например, "") |
Обратите внимание, что LMS может поддерживать сортировку из чисел, отличных от 100. В этом случае (maxMark не равно 100) OneNote может потребоваться преобразовать полученную оценку, если её невозможно отобразить в пользовательском интерфейсе OneNote.
Поставьте оценку учащемуся
Выполнить POST запрос<Specify URL for setting grade for a given student>.
Могут быть включены следующие переменные формы, передаваемой методом POST:
| Имя свойства | Тип | Описание |
|---|---|---|
| id | строка | Идентификатор для ученика, руководство |
| источник | строка | Всегда устанавливайте значение " onenote" |
| obtainedMark | целое число | Оценка, полученная учеником |
| maxMark | целое число | Максимально возможная достижимая оценка |
| obtainedGrade | строка | Оценка или уровень, достигнутый учащимся (например: "") |
| комментарии | строка | Бесплатная текстовая обратная связь для учащегося |
Получение типов оценок
Выполнить GET запрос<Specify URL for getting grade types>.
LMS должен возвращать массив JSON типа оценок. У каждого типа оценок должны быть следующие свойства:
| Имя свойства | Тип | Описание |
|---|---|---|
| id | строка | Идентификатор типа класса, уникальный на установке LMS |
| gradeTypeCategory | GradeTypeCategory | Идентификатор типа класса, уникальный на установке LMS |
| макс. | целое число | Максимальный возможный балл |
| описание | строка | Отображает строку типа оценок |
Получение определенного типа оценки
Выполнить GET запрос<Specify URL for getting grade type by id>.
LMS должен вернуть JSON одного типа оценок, который обладает следующими свойствами:
| Имя свойства | Тип | Описание |
|---|---|---|
| id | строка | Идентификатор типа класса, уникальный на установке LMS |
| gradeTypeCategory | GradeTypeCategory | Идентификатор типа класса, уникальный на установке LMS |
| макс. | целое число | Максимальный возможный балл |
| описание | строка | Отображает строку типа оценок |
Создание/удаление классов и удаление заданий
Они являются необязательными, но настоятельно рекомендуется иметь для тестирования интеграции. Команда Microsoft Class Notebook использует данные конечные критерии оценки для очистки данных.
enum GradeTypeCategory
{
/// <summary>
/// no grade type category.
/// </summary>
None,
/// <summary>
/// Numeric grade type category.
/// </summary>
Numeric,
/// <summary>
/// Percent grade type category.
/// </summary>
Percentage,
/// <summary>
/// Letter grade type category.
/// </summary>
Letters,
}
Необходимые условия тестовой среды
Ваша тестовая среда состоит из двух систем:
Тестовый клиент Office 365
Это может быть любой клиент Office 365, к которому у вас есть доступ, и есть несколько учетных записей преподавателей и учащихся с действующими рабочими лицензиями.
Демонстрационный клиент Office 365 клиента доступен для партнеров. Когда вы настраиваете эту демонстрационную версию клиента, вы можете выбрать индивидуальный экземпляр K-12 EDU, который будет заполнен данными преподавателей и учащихся, а также средствми учета для образовательных учреждений.–
Условия тестирования и учетные записи LMS
Вам необходимо будет предоставить команде Class Notebook следующую информацию:
- Базовый URL вашего LMS / SIS, на котором размещаются конечные точки API.
- Идентификатор приложения (если у вас не поддерживается oauth2) –это уникальный идентификатор приложения, назначенный для надстройки журнала класса, позволяющий определять его, как допустимое приложение.
- Ключ приложения (если у вас не поддерживается oauth2) — это секретный код приложения для данного идентификатора приложения.
Необходимые условия для маркетинговых данных
Изображение логотипа. У изображения не обязательно должно быть сверхвысокое разрешение. На самом деле размер наших текущих логотипов меньше 100 Кбайт, а максимальный размер в пикселях — 300 x 300.
Описание. Сообщение с описанием вашего предложения должно быть коротким, приблизительно 75 слов (лучше, если около 50).
Ссылка на ваш сайт. Предназначено для того, чтобы узнать больше о вашем предложении.
Изображение на кнопке. Должно быть 64 x 64 пикселя.