이 페이지에서는 첨부파일을 만들고 학생 제출물을 처리하기 위한 구현 세부정보를 설명합니다. 이러한 요청을 수행할 때는 첨부파일 관련 매개변수를 제공해야 할 수도 있습니다.
연결 만들기
적절한 courses.*.addOnAttachments.create
엔드포인트에 CREATE
요청을 실행하여 연결을 만듭니다. 요청의 요청 본문에 AddOnAttachment
인스턴스가 포함되어야 합니다.
첨부파일을 만들 때는 다음 필드가 필요합니다.
title
: 첨부파일의 문자열 이름입니다.teacherViewUri
: 첨부파일의 교사 보기용 URI입니다.studentViewUri
: 첨부파일의 학생 뷰 URI입니다.studentWorkReviewUri
: 교사가 첨부파일에서 학생의 과제물을 볼 수 있는 URI입니다. 이 필드는 활동 유형 첨부파일에만 필요합니다.
다음과 같은 선택적인 필드를 포함할 수 있습니다.
- 첨부파일 만료일을 지정하는 경우
dueDate
및dueTime
입니다. maxPoints
: 첨부파일의 최대 성적입니다. 성적 반환을 지원하려면 0이 아닌 값이어야 합니다. 활동 유형 첨부파일에만 적용됩니다.
이 필드에 대한 자세한 내용은 AddOnAttachment
리소스 참조를 확인하세요.
학생 제출물 세부정보
일반적인 제출 워크플로는 다음 단계를 따릅니다.
- 학생이
studentViewUri
를 실행하여 활동을 완료합니다. - 부가기능은 학생 사용자 인증 정보를 사용하여
getAddOnContext
메서드에서submissionId
를 검색합니다. submissionId
및attachmentId
는 부가기능 개발자가 학생 과제물의 고유 식별자로 저장합니다. 교사가 클래스룸에서 과제를 복사한 경우 이 두 매개변수의 복합 키를 사용하여 복사된 과제에 새 첨부파일을 표시할 수 있습니다. 자세한 내용은 복사된 콘텐츠 페이지를 참고하세요.- 학생 과제물을 검토하는 데 관심이 있는 교사가
studentWorkReviewUri
를 실행합니다. 요청에는courseId
,itemId
,itemType
,attachmentId
,submissionId
쿼리 매개변수가 포함됩니다. - 부가기능 개발자는 이 4개의 ID를 사용하여 학생 과제물을 검색합니다.
courses.courseWork.addOnAttachments.studentSubmissions
엔드포인트를 사용하여 학생 제출물에 대한 정보를 검색하거나 수정합니다.
제출 상태 감지
courses.courseWork.addOnAttachments.studentSubmissions
엔드포인트에 GET
요청을 실행하여 특정 submissionId
의 세부정보를 가져옵니다. 제출 성적(pointsEarned
) 및 현재 상태 (postSubmissionState
)가 포함된 AddOnAttachmentStudentSubmission
객체가 수신됩니다. 제출 상태는 다음 값 중 하나일 수 있습니다.
NEW
: 학생이 제출물에 액세스한 적이 없는 경우CREATED
: 학생이 제출물을 만들었지만 아직 제출하지 않은 경우TURNED_IN
: 학생이 교사에게 과제물을 제출한 경우RETURNED
: 교사가 제출물을 학생에게 돌려준 경우RECLAIMED_BY_STUDENT
: 학생이 과제물을 '제출 취소'한 경우
이 엔드포인트를 사용하여 부가기능에서 학생의 과제 상태를 감지합니다. 그런 다음 반환된 상태에 따라 학생에게 제공되는 뷰 또는 옵션을 조정할 수 있습니다. 여기에는 다음과 같은 기능이 포함될 수 있습니다.
- 부가기능 내에서 과제 제출 상태를 표시합니다. 이렇게 하면 학생들이 혼란을 겪지 않고 실수로 과제를 제출하지 못하게 하는 데 도움이 될 수 있습니다.
- 제출물 수정 권한을 제한합니다. 과제의 상태가
CREATED
또는RECLAIMED_BY_STUDENT
인 경우 학생은 제출물을 수정할 수 있습니다. 과제의 상태가TURNED_IN
또는RETURNED
인 경우 학생이 제출물을 수정하지 못할 수 있습니다.
성적 및 여러 첨부파일
하나의 과제의 성적을 설정하는 데 하나의 부가기능 첨부파일만 사용할 수 있습니다. 교사가 maxPoints
값을 제공하는 활동 유형 첨부파일을 두 개 이상 만드는 경우 첫 번째 첨부파일만 과제 성적을 설정할 수 있습니다. maxPoints
값을 설정하지 않거나 0으로 설정하여 첨부파일의 성적 패스백을 사용 중지합니다.
제출물 성적 설정하기
courses.courseWork.addOnAttachments.studentSubmissions
엔드포인트에 PATCH
요청을 전송하여 학생 제출물을 수정할 수 있습니다. 요청 본문에는 값이 수정된 AddOnAttachmentStudentSubmission
인스턴스가 포함되어야 합니다. 제출물의 성적을 수정하려면 pointsEarned
필드를 설정합니다.
pointsEarned
에 전달된 값은 클래스룸 UI에서 교사가 볼 수 있는 초안 성적이 됩니다. 교사는 과제를 학생에게 돌려주기 전에
임시 성적을 수정할 수 있습니다 교사에게 성적이 표시되는 방식에 관한 자세한 내용은 클래스룸 UI의 채점 개요를 참고하세요.
다음 조건을 충족하는 경우에만 pointsEarned
로 성적을 설정할 수 있습니다.
- 첨부파일의
maxPoints
값이 양수여야 합니다. - 첨부파일을 처음 만든 부가기능이어야 합니다.
addOnAttachments
엔드포인트에 PATCH
요청을 실행하여 이미 만든 AddOnAttachment
의 maxPoints
값을 수정할 수도 있습니다.
성적을 설정해야 하는 경우
교사는 성적이 Google 클래스룸으로 다시 전달되는 시점을 선택할 수 있습니다. 교사만 성적을 수정할 수 있으므로 교사의 사용자 인증 정보를 저장할지 여부는 중요한 차이점입니다.
Google 클래스룸에 성적이 전달될 수 있는 두 가지 부가기능이 있습니다. 즉, 학생이 과제를 완료하는 시점과 교사가 학생 과제물 검토 iframe에서 학생의 과제를 여는 시점입니다.
학생이 과제를 완료할 때 성적을 설정하려면 교사의 오프라인 사용자 인증 정보를 저장한 다음 학생이 과제를 완료할 때 이를 검색하여 성적을 수정하는 데 사용해야 합니다. 이 방법에는 몇 가지 잠재적인 이점이 있습니다.
- 원활한 성적 업데이트를 제공합니다. 교사는 특별한 조치를 취하지 않아도 클래스룸 UI에 성적이 채워집니다.
- 과제를 통해 수업의 진행 상황을 실시간으로 파악할 수 있습니다. 학생이 첨부파일을 완료할 때마다 성적을 설정하면 교사는 제출물을 일일이 열지 않고도 학생이 이해했는지 파악할 수 있습니다.
이 접근 방식을 사용하면 비동기식 접근 방식으로도 채점이 가능합니다. 주기적으로 AddOnAttachmentStudentSubmission
엔드포인트를 폴링하여 학생이 과제물을 제출한 시점을 감지할 수 있습니다. 제출이 완료되면 저장된 사용자 인증 정보를 사용하여 제출물의 등급을 설정합니다.
학생 세션 중에 교사의 사용자 인증 정보를 로드하지 않으려면 활성 교사가 학생 과제물 검토 iframe에 학생의 제출물을 로드할 때 활성 교사의 사용자 인증 정보를 사용하면 됩니다. 하지만 클래스룸 UI의 성적이 실시간으로 업데이트되지 않고 교사가 제출된 모든 제출물의 학생 과제물 리뷰 iframe을 열어야 하므로 사용자 환경이 원활하지 않을 수 있습니다.
과제 성적의 변화 감지하기
교사는 과제를 만든 후에도 클래스룸에서 성적 설정을 수정할 수 있습니다 이러한 수정에는 다음이 포함될 수 있습니다.
- 할당된 포인트 값 변경
- 과제의
maxPoints
값 변경 - 과제 채점 여부 변경
과제의 현재 평가 설정을 보려면 courses.courseWork
엔드포인트에 GET
요청을 전송하는 것이 좋습니다. 응답에 현재 maxPoints
값이 포함됩니다. 미채점 과제의 maxPoints
값은 null 또는 0입니다.
성적을 클래스룸으로 다시 전달한 경우 courses.courseWork.addOnAttachments.studentSubmissions
엔드포인트를 사용하여 부가기능 첨부파일의 성적을 가져오거나 변경합니다. 성적 값은 pointsEarned
필드를 사용하여 설정됩니다. 제품에서 교사가 특정 활동에 대한 학생의 점수를 수정할 수 있는 경우 이 값을 확인하고 필요한 경우 업데이트하는 것이 좋습니다.