Стандарты API LMS для интеграции надстроек классного журнала OneNote

Статья
04/13/2017

Область применения: корпоративные записные книжки в 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 пикселя.

Поделиться через