이 페이지에서는 첨부파일을 만들고 학생 제출물을 처리하기 위한 구현 세부정보를 설명합니다. 이러한 요청을 수행할 때는 첨부파일 관련 매개변수를 제공해야 할 수도 있습니다.
연결 만들기
적절한 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쿼리 매개변수가 포함됩니다. - 부가기능 개발자는 이 네 가지 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값을 변경합니다. - 과제에 성적을 부여할지 여부를 변경합니다.
과제의 현재 채점 설정을 보려면 GET 요청을 courses.courseWork 엔드포인트에 보내는 것이 좋습니다. 응답에는 현재 maxPoints 값이 포함됩니다. 채점되지 않은 과제에는 null 또는 0 maxPoints 값이 있습니다.
성적을 클래스룸으로 다시 전달한 경우 courses.courseWork.addOnAttachments.studentSubmissions 엔드포인트를 사용하여 부가기능 첨부파일의 성적을 가져오거나 수정합니다. 성적 값은 pointsEarned 필드를 사용하여 설정됩니다. 제품에서 교사가 특정 활동에 대한 학생의 점수를 수정할 수 있는 경우 이 값을 확인하고 필요한 경우 업데이트해 보세요.