이 페이지에서는 첨부파일을 만들고 학생 제출물로 작업하기 위한 구현 세부정보를 설명합니다. 이러한 요청을 할 때 연결 관련 매개변수를 제공해야 할 수도 있습니다.
연결 만들기
적절한 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에 대한 세부정보를 가져옵니다. AddOnAttachmentStudentSubmission 객체를 수신하며 여기에는 제출물의 성적(pointsEarned)과 현재 상태 (postSubmissionState)가 포함됩니다. 제출 상태는 다음 값 중 하나일 수 있습니다.
NEW: 학생이 제출물에 액세스한 적이 없는 경우CREATED: 학생이 과제를 만들었지만 아직 제출하지 않은 경우TURNED_IN: 학생이 교사에게 과제물을 제출한 경우RETURNED: 교사가 제출물을 학생에게 반환한 경우RECLAIMED_BY_STUDENT: 학생이 과제물을 '제출 취소'한 경우
이 엔드포인트를 사용하여 부가기능에서 학생 과제물의 상태를 감지할 수 있습니다. 그런 다음 반환된 상태에 따라 학생에게 제공되는 뷰 또는 옵션을 조정할 수 있습니다. 여기에는 다음과 같은 기능이 포함될 수 있습니다.
- 부가기능 내 과제 제출 상태를 표시합니다. 이렇게 하면 학생들이 혼란을 겪지 않고 실수로 과제를 제출하는 것을 방지할 수 있습니다.
- 제출물 수정 권한을 제한합니다. 과제의 상태가
CREATED또는RECLAIMED_BY_STUDENT이면 학생이 제출물을 수정할 수 있습니다. 과제가TURNED_IN또는RETURNED상태인 경우 학생은 제출물을 수정하지 못할 수 있습니다.
성적 및 여러 첨부파일
하나의 부가기능 연결은 하나의 과제만 성적을 설정하는 데 사용할 수 있습니다. 교사가 maxPoints 값을 제공하는 활동 유형 첨부파일을 2개 이상 만드는 경우 첫 번째 첨부파일만 과제 성적을 설정할 수 있습니다. 첨부파일의 성적 반환을 사용 중지하려면 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 필드를 사용하여 설정됩니다. 제품을 통해 교사가 특정 활동에 대한 학생 점수를 수정할 수 있는 경우 이 값을 확인하고 필요한 경우 업데이트하는 것이 좋습니다.