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

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

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

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

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

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

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

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

Дополнительные сведения об этих полях см. в справочнике по ресурсу AddOnAttachment .

Детали подачи заявок студентами

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

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

Важно: при отправке запросов PATCH не забудьте также указать updateMask . Значение updateMask должно представлять собой список имен полей, разделенных запятыми, которые необходимо изменить.

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

Выполните запрос 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 становится черновой оценкой , видимой учителю в пользовательском интерфейсе Класса. Учителя могут изменить черновую оценку, прежде чем вернуть задание учащимся. Подробную информацию о том, как оценки выставляются учителям, см. в разделе «Обзор оценок в пользовательском интерфейсе Класса».

Предупреждение. Обновление оценок в пользовательском интерфейсе Google Classroom не происходит в режиме реального времени. Между успешным получением оценки и ее отображением в Классе может пройти до 30 секунд.

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

• Вложение должно иметь положительное значение maxPoints .
• Надстройка должна быть первоначальным создателем вложения.

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

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

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

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

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

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

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

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

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

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

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

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

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

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