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

This page discusses implementation details for creating an attachment, recommended actions when users open attachments, and working with student submissions. Note that you may need to supply attachment-related parameters when making making these requests.

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

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

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

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

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

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

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

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

The Student View iframe , Student Work Review iframe , and Teacher View iframe are all intended to present content to the user rather than modifying a Classroom assignment. Consider doing the following when one of these views open:

• Получите учетные данные OAuth для пользователя.
• Для проверки роли пользователя выполните запрос courseWork.getAddOnContext , courseWorkMaterials.getAddOnContext или announcements.getAddOnContext в зависимости от itemType .
• Проверьте ответ, чтобы убедиться, присутствует ли в нем объект TeacherContext или StudentContext . Может быть возвращен только один из них, соответствующий роли пользователя в курсе.
• If the current user is a student and the itemType is courseWork , record the submissionId from the response with the student's work. The submissionIds match across add-on iframes, and are required for passing back grades and for showing student work to teachers in the grading tool.
• Если attachmentId уже известен дополнению, отобразите соответствующий интерфейс для работы с вложениями.
• В противном случае, это вложение, должно быть, скопировано из другого элемента потока или курса. Рекомендации по этому сценарию см. в руководстве по обработке скопированного контента .

Информация о подаче документов студентом

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

1. Студент запускает studentViewUri для выполнения задания.
2. Дополнение получает идентификатор submissionId из метода getAddOnContext , используя учетные данные студента.
3. The submissionId and attachmentId are stored by the add-on developer as the unique identifier of the student's work. In the event that a teacher copies an assignment in Classroom, you can use the composite key of these two parameters to display a new attachment in the copied assignment. See our page on copied content for more details.
4. A teacher interested in reviewing student work launches the studentWorkReviewUri . The request includes the following query parameters: courseId , itemId , itemType , attachmentId , and submissionId .
5. The add-on developer uses these four IDs to retrieve the student work. Use the courses.courseWork.addOnAttachments.studentSubmissions endpoint to retrieve or modify information about a student submission.

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

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

Issue a GET request to the courses.courseWork.addOnAttachments.studentSubmissions endpoint to get details about a specific submissionId . You receive an AddOnAttachmentStudentSubmission object, which contains the submission's grade ( pointsEarned ) and current state ( postSubmissionState ). The submission state can be one of the following values:

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

Use this endpoint to detect the state of the student's work in your add-on. You might then adjust the views or options provided to the student depending on the state returned. This might include features such as:

• Отображение статуса сдачи заданий в вашем дополнении. Это может помочь студентам избежать потенциальной путаницы и гарантировать, что они по ошибке не сдадут задание.
• Restricting submission edit privileges. If the assignment has status CREATED or RECLAIMED_BY_STUDENT , the student might be allowed to edit their submission. If the assignment has status TURNED_IN or RETURNED , the student might not be allowed to edit their submission.

Оценки и множественные вложения

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

Only one add-on attachment can be used to set the grade for a single assignment . If a teacher creates more than one activity-type attachment that provides a maxPoints value, only the first such attachment can set the assignment grade. Either leave the maxPoints value unset or set it to zero to disable grade passback for an attachment.

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

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

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

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

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

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

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

You have some choice over when a grade is passed back to Google Classroom. The critical distinction is whether you choose to store teacher's credentials, as only the teacher can modify a grade.

There are two add-on moments at which you might pass a grade to Google Classroom: when the student completes their work or when the teacher opens the student's work in the Student Work Review iframe.

If you want to set grades when the student completes the work, you must store a teacher's offline credentials, then retrieve and use them to modify the grade when the student completes the work. This method provides some potential benefits:

• Обеспечьте бесперебойное обновление оценок. Учителям не нужно предпринимать никаких специальных действий для отображения оценок в пользовательском интерфейсе Classroom.
• Provide real-time insight into a class's progression through an assignment. By setting grades as students complete attachments, teachers can get a sense of their students' understanding without opening every submission.

Note that this approach also allows for an asynchronous approach to grade sync. You might periodically poll the AddOnAttachmentStudentSubmission endpoint to detect when a student has submitted their work. When it has been submitted, set the submission's grade using the stored credentials.

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

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

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

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

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

To see the current grading settings of an assignment, we recommend that you send a GET request to the courses.courseWork endpoint. The response includes the current maxPoints value. An ungraded assignment has a null or zero maxPoints value.

If you have passed a grade back to Classroom, use the courses.courseWork.addOnAttachments.studentSubmissions endpoint to fetch or alter the grade for an add-on attachment. The grade value is set using the pointsEarned field. Consider checking and, if necessary, updating this value if your product allows teachers to edit a student's score for a particular activity.