На этой странице обсуждаются детали реализации для создания вложения, рекомендуемые действия, когда пользователи открывают вложения, и работа с заявками студентов. Обратите внимание, что вам может потребоваться предоставить параметры, связанные с вложением, при выполнении этих запросов.
Создать вложение
Создайте вложение, отправив запрос CREATE
на соответствующую конечную courses.*.addOnAttachments.create
. Ваш запрос должен включать экземпляр AddOnAttachment
в теле запроса.
При создании вложения обязательными являются следующие поля:
-
title
: строковое имя вложения. -
teacherViewUri
: URI для представления вложения учителем. -
studentViewUri
: URI для студенческого представления вложения. -
studentWorkReviewUri
: URI для учителя, чтобы увидеть работу студента во вложении. Это поле обязательно только для вложений типа активности.
Вы можете включить некоторые из следующих необязательных полей:
-
dueDate
иdueTime
если указывается, когда необходимо сдать вложение. -
maxPoints
: максимальная оценка для вложения. Должно быть ненулевым значением, если вы хотите поддерживать обратную передачу оценок. Применимо только к вложениям типа «активность».
Более подробную информацию об этих полях см. в справочнике по ресурсам AddOnAttachment
Проверка учетных данных и роли пользователя
iframe Student View , Student Work Review и Teacher View предназначены для представления контента пользователю, а не для изменения задания Classroom. Рассмотрите возможность выполнения следующих действий при открытии одного из этих представлений:
- Получите учетные данные OAuth для пользователя.
- Создайте запрос
courseWork.getAddOnContext
,courseWorkMaterials.getAddOnContext
илиannouncements.getAddOnContext
на основеitemType
для проверки роли пользователя. - Проверьте ответ, чтобы увидеть, присутствуют ли
TeacherContext
илиStudentContext
. Может быть возвращен только один, соответствующий роли пользователя в курсе. - Если текущий пользователь — студент, а
itemType
—courseWork
, запишитеsubmissionId
из ответа с работой студента.submissionIds
совпадают во всех дополнительных фреймах и требуются для передачи оценок и для показа работ студентов учителям в инструменте оценки. - Если
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 Student Work Review . Однако это может не обеспечить особенно гладкого пользовательского опыта, поскольку оценки в пользовательском интерфейсе Classroom не обновляются в режиме реального времени, и учителям придется открывать iframe Student Work Review каждой работы.
Обнаружение изменений в оценках заданий
учителя могут редактировать настройки оценок в Classroom после создания задания. Такие изменения могут включать:
- Изменение значения присвоенных баллов.
- Изменение значения
maxPoints
задания. - Изменение того, следует ли вообще оценивать задание.
Чтобы увидеть текущие настройки оценок задания, мы рекомендуем вам отправить запрос GET
на конечную точку courses.courseWork
. Ответ включает текущее значение maxPoints
. Неоцененное задание имеет нулевое или нулевое значение maxPoints
.
Если вы передали оценку обратно в Classroom, используйте конечную точку courses.courseWork.addOnAttachments.studentSubmissions
, чтобы получить или изменить оценку для прикрепленного дополнения. Значение оценки задается с помощью поля pointsEarned
. Рассмотрите возможность проверки и, при необходимости, обновления этого значения, если ваш продукт позволяет учителям редактировать оценку студента за определенную деятельность.