Дополнения Google Classroom теперь общедоступны для разработчиков! Дополнительную информацию см. в документации по дополнениям .

Эта страница переведена с помощью Cloud Translation API.

Взаимодействие с вложениями

На этой странице обсуждаются детали реализации создания вложений, рекомендуемые действия при открытии вложений пользователями и работа с работами студентов. Обратите внимание, что при выполнении таких запросов вам может потребоваться указать параметры, связанные с вложениями .

Создать вложение

Создайте вложение, отправив запрос CREATE к соответствующей courses.*.addOnAttachments.create . В теле запроса необходимо указать экземпляр AddOnAttachment .

При создании вложения обязательными являются следующие поля:

title : строковое имя вложения.
teacherViewUri : URI для представления вложения учителем.
studentViewUri : URI для студенческого представления вложения.
studentWorkReviewUri : URI, по которому преподаватель может увидеть работу студента над вложением. Это поле обязательно для заполнения только для вложений типа «задание».

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

dueDate и dueTime если указываете, когда следует сдать вложение.
maxPoints : максимальная оценка за вложение. Значение должно быть ненулевым, если требуется поддержка обратной передачи оценок. Применяется только к вложениям типа «занятие».

Более подробную информацию об этих полях см. в справочнике ресурсов AddOnAttachment

Проверка учетных данных и роли пользователя

Окна iframe «Просмотр работы студента» , iframe «Обзор работы студента» и iframe «Просмотр работы преподавателя» предназначены для представления контента пользователю, а не для редактирования задания в классе. При открытии одного из этих окон выполните следующие действия:

Получите учетные данные OAuth для пользователя.
Создайте запрос courseWork.getAddOnContext , courseWorkMaterials.getAddOnContext или announcements.getAddOnContext на основе itemType для проверки роли пользователя.
Проверьте ответ на наличие TeacherContext или StudentContext . Возврат возможен только в одном случае, соответствующем роли пользователя в курсе.
Если текущий пользователь — студент, а itemType — courseWork , запишите идентификатор submissionId из ответа с работой студента. submissionIds совпадают во всех надстройках iframe и необходимы для передачи оценок и отображения работ студентов преподавателям в инструменте оценки.
Если attachmentId уже известен дополнению, отобразите соответствующий пользовательский интерфейс вложения.
В противном случае, это вложение, вероятно, было скопировано из другого элемента потока или курса. Рекомендации по этому сценарию см. в руководстве «Обработка скопированного контента» .

Подробная информация о студенческих работах

Типичный рабочий процесс отправки состоит из следующих шагов:

Студент запускает studentViewUri для завершения действия.
Дополнение извлекает submissionId из метода getAddOnContext , используя учетные данные студента.
Разработчик дополнения сохраняет значения submissionId и attachmentId как уникальный идентификатор работы учащегося. Если преподаватель копирует задание в Classroom, вы можете использовать составной ключ этих двух параметров для отображения нового вложения в скопированном задании. Подробнее см. на странице о скопированном контенте .
Преподаватель, заинтересованный в проверке студенческих работ, запускает studentWorkReviewUri . Запрос включает следующие параметры: courseId , itemId , itemType , attachmentId и submissionId .
Разработчик дополнения использует эти четыре идентификатора для получения студенческих работ. Для получения или изменения информации о студенческих работах используйте конечную точку courses.courseWork.addOnAttachments.studentSubmissions .

Определить состояние отправки

Отправьте запрос GET к конечной точке courses.courseWork.addOnAttachments.studentSubmissions , чтобы получить сведения о заданном идентификаторе ( submissionId ). Вы получите объект AddOnAttachmentStudentSubmission , содержащий оценку ( pointsEarned ) и текущее состояние ( postSubmissionState ) работы. Состояние работы может принимать одно из следующих значений:

NEW , если студент никогда не открывал представленную работу.
CREATED , если студент создал работу, но еще не отправил ее.
TURNED_IN , если ученик сдал свою работу преподавателю.
RETURNED , если преподаватель вернул работу студенту.
RECLAIMED_BY_STUDENT , если студент «отменил» свою работу.

Используйте эту конечную точку для определения состояния работы учащегося в вашем дополнении. Затем вы можете настроить представления или параметры, предоставляемые учащемуся, в зависимости от возвращаемого состояния. Это может включать в себя такие функции, как:

Отображение статуса сдачи заданий в вашем дополнении. Это поможет учащимся избежать возможных недоразумений и убедиться, что они по ошибке не сдадут задание.
Ограничение прав на редактирование работы. Если работа имеет статус CREATED или RECLAIMED_BY_STUDENT , студенту может быть разрешено редактировать свою работу. Если работа имеет статус TURNED_IN или RETURNED , студенту может быть запрещено редактировать свою работу.

Сорта и множественные вложения

Для установки оценки за одно задание можно использовать только одно вложение-дополнение . Если преподаватель создаёт несколько вложений типа «задание» со значением maxPoints , оценку за задание можно установить только для первого из них. Чтобы отключить обратную передачу оценок для вложения, оставьте значение maxPoints неизменным или установите его равным нулю.

Установить оценку отправленной работы

Вы можете изменить работу студента, отправив запрос PATCH к конечной точке courses.courseWork.addOnAttachments.studentSubmissions . Тело запроса должно включать экземпляр AddOnAttachmentStudentSubmission с изменёнными значениями. Задайте поле pointsEarned , чтобы изменить оценку за работу. Значение, переданное в pointsEarned становится черновой оценкой, которую преподаватель видит в интерфейсе «Класс». Преподаватели могут изменить черновую оценку перед возвратом работы студентам. Подробную информацию о том, как оценки отображаются для преподавателей, см. в разделе «Обзор оценивания в интерфейсе «Класс».

Обратите внимание, что вы можете установить оценку с помощью pointsEarned только в том случае, если выполняются следующие условия:

Вложение должно иметь положительное значение maxPoints .
Дополнение должно быть изначальным создателем вложения.

Также обратите внимание, что вы можете изменить значение maxPoints уже созданного AddOnAttachment , отправив запрос PATCH к конечной точке addOnAttachments .

Когда ставить оценку

У вас есть выбор, когда оценка будет передана обратно в Google Classroom. Ключевое отличие заключается в том, сохраняете ли вы учётные данные учителя, поскольку изменять оценку может только учитель.

Есть два дополнительных момента, когда вы можете передать оценку в Google Classroom: когда ученик завершает свою работу или когда учитель открывает работу ученика в iframe «Обзор работ ученика».

Если вы хотите выставлять оценки после завершения работы учеником, необходимо сохранить офлайн-учётные данные учителя, а затем извлечь их и использовать для изменения оценки после завершения работы учеником. Этот метод даёт несколько потенциальных преимуществ:

Обеспечьте бесперебойное обновление оценок. Учителям не нужно предпринимать никаких специальных действий, чтобы оценки появились в интерфейсе класса.
Предоставляйте информацию о ходе выполнения задания классом в режиме реального времени. Выставляя оценки по мере того, как ученики заполняют вложения, учителя могут оценить уровень понимания материала учениками, не открывая каждую работу.

Обратите внимание, что этот подход также допускает асинхронную синхронизацию оценок. Вы можете периодически опрашивать конечную точку AddOnAttachmentStudentSubmission , чтобы определить, сдала ли студент свою работу. После отправки работы установите оценку, используя сохранённые учётные данные.

Если вы не хотите загружать учётные данные преподавателя во время сеанса работы с учеником, вы можете использовать учётные данные текущего преподавателя при загрузке работы учащегося в iframe «Обзор работ учащихся» . Однако это может быть не очень удобно, поскольку оценки в интерфейсе класса не обновляются в режиме реального времени, и преподавателям придётся открывать iframe «Обзор работ учащихся» для каждой работы.

Обнаружение изменений в оценках заданий

Преподаватели могут редактировать настройки оценок в Classroom после создания задания. Такие изменения могут включать:

Изменение значения присвоенных баллов.
Изменение значения maxPoints задания.
Изменение того, следует ли вообще оценивать задание.

Чтобы просмотреть текущие настройки оценок задания, рекомендуем отправить GET запрос к конечной точке courses.courseWork . Ответ будет содержать текущее значение maxPoints . Неоценённое задание имеет значение maxPoints , равное нулю или равное нулю.

Если вы передали оценку обратно в Classroom, используйте конечную точку courses.courseWork.addOnAttachments.studentSubmissions для получения или изменения оценки за прикрепленный дополнительный файл. Значение оценки задаётся в поле pointsEarned . Рекомендуем проверить и при необходимости обновить это значение, если ваш продукт позволяет преподавателям редактировать оценку учащегося за определённое задание.