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

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

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

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

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

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

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

title : строковое имя вложения.
teacherViewUri : URI для представления вложения в режиме "Учитель".
studentViewUri : URI для просмотра вложения в режиме для студентов.
studentWorkReviewUri : URI, по которому преподаватель может просмотреть работу ученика в прикрепленном файле. Это поле обязательно только для прикрепленных файлов типа "Задание".

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

Укажите dueDate и dueTime если необходимо указать срок сдачи вложения.
maxPoints : максимальная оценка за вложенный файл. Для поддержки обратной передачи оценок необходимо ненулевое значение. Применяется только к вложенным файлам типа "деятельность".

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

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

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

Получите учетные данные 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 для получения или изменения информации о студенческой работе.

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

Чтобы получить подробную информацию о конкретном submissionId ), отправьте GET запрос к конечной точке courses.courseWork.addOnAttachments.studentSubmissions . Вы получите объект 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 становится черновой оценкой, видимой преподавателю в пользовательском интерфейсе Classroom. Преподаватели могут изменить черновую оценку перед отправкой задания студентам. Подробную информацию о том, как оценки отображаются преподавателям, см. в разделе «Обзор оценивания в пользовательском интерфейсе Classroom».

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

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

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

Когда выставлять оценку

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

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

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

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

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

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

Выявление изменений в оценках за задания.

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

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

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

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