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

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

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

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

Подробности студенческой заявки

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

  1. Студент запускает studentViewUri для завершения задания.
  2. Дополнение извлекает submissionId из метода getAddOnContext , используя учетные данные студента.
  3. submissionId и attachmentId сохраняются разработчиком дополнения как уникальный идентификатор работы ученика. В случае, если учитель копирует задание в Classroom, вы можете использовать составной ключ этих двух параметров для отображения нового вложения в скопированном задании. Подробнее см. на нашей странице о скопированном контенте .
  4. Преподаватель, заинтересованный в проверке студенческих работ, запускает studentWorkReviewUri . Запрос включает следующие параметры запроса: courseId , itemId , itemType , attachmentId и submissionId .
  5. Разработчик надстройки использует эти четыре идентификатора для извлечения студенческой работы. Используйте конечную точку 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 . Рассмотрите возможность проверки и, при необходимости, обновления этого значения, если ваш продукт позволяет учителям редактировать оценку студента за определенную деятельность.