이 페이지에서는 첨부파일 생성, 사용자가 첨부파일을 열 때 권장되는 작업, 학생 제출물 작업에 관한 구현 세부정보를 설명합니다. 이러한 요청을 할 때는 첨부파일 관련 매개변수를 제공해야 할 수 있습니다.
연결 만들기
적절한 courses.*.addOnAttachments.create 엔드포인트에 CREATE 요청을 실행하여 첨부파일을 만듭니다. 요청 본문에 AddOnAttachment 인스턴스를 포함해야 합니다.
첨부파일을 만들 때 다음 필드가 필요합니다.
title: 연결의 문자열 이름입니다.teacherViewUri: 첨부파일의 교사 보기 URI입니다.studentViewUri: 첨부파일의 학생 보기 URI입니다.studentWorkReviewUri: 교사가 첨부파일에서 학생의 과제를 확인할 수 있는 URI입니다. 이 필드는 활동 유형 첨부파일에만 필요합니다.
다음 선택적 필드를 포함할 수 있습니다.
- 첨부파일의 기한을 지정하는 경우
dueDate및dueTime maxPoints: 첨부파일의 최대 등급입니다. 성적 되돌리기를 지원하려면 0이 아닌 값이어야 합니다. 활동 유형 첨부파일에만 적용됩니다.
이러한 필드에 대한 자세한 내용은 AddOnAttachment 리소스 참조를 확인하세요.
사용자 인증 정보 및 역할 검증
학생 보기 iframe, 학생 과제 검토 iframe, 교사 보기 iframe은 모두 클래스룸 과제를 수정하는 대신 사용자에게 콘텐츠를 표시하기 위한 것입니다. 이러한 뷰 중 하나가 열리면 다음 작업을 수행하는 것이 좋습니다.
- 사용자의 OAuth 사용자 인증 정보를 가져옵니다.
itemType에 따라courseWork.getAddOnContext,courseWorkMaterials.getAddOnContext또는announcements.getAddOnContext요청을 만들어 사용자 역할을 확인합니다.- 응답을 검사하여
TeacherContext또는StudentContext이 있는지 확인합니다. 과정에서 사용자의 역할에 해당하는 값 하나만 반환됩니다. - 현재 사용자가 학생이고
itemType이courseWork인 경우 학생의 과제와 함께 응답에서submissionId을 기록합니다.submissionIds는 부가기능 iframe에서 일치해야 하며, 성적을 다시 전달하고 채점 도구에서 교사에게 학생 과제를 표시하는 데 필요합니다. attachmentId이 부가기능에 이미 알려진 경우 적절한 첨부파일 UI를 표시합니다.- 그렇지 않은 경우 이 첨부파일은 다른 스트림 항목이나 강의에서 복사된 것이어야 합니다. 이 시나리오에 관한 권장사항은 복사된 콘텐츠 처리 가이드를 참고하세요.
학생 제출물 세부정보
일반적인 제출 워크플로는 다음 단계를 따릅니다.
- 학생이
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값을 변경합니다. - 과제에 성적을 부여할지 여부를 변경합니다.
과제의 현재 채점 설정을 확인하려면 courses.courseWork 엔드포인트에 GET 요청을 보내는 것이 좋습니다. 응답에는 현재 maxPoints 값이 포함됩니다. 미채점 과제에는 null 또는 0 maxPoints 값이 있습니다.
성적을 클래스룸으로 다시 전달한 경우 courses.courseWork.addOnAttachments.studentSubmissions 엔드포인트를 사용하여 부가기능 첨부파일의 성적을 가져오거나 변경합니다. 등급 값은 pointsEarned 필드를 사용하여 설정됩니다. 제품에서 교사가 특정 활동에 대한 학생의 점수를 수정할 수 있는 경우 이 값을 확인하고 필요한 경우 업데이트하세요.