이제 Google 클래스룸 부가기능이 일반적으로 개발자에게 제공됩니다. 자세한 내용은 부가기능 문서를 참고하세요.

첨부파일과 상호작용

이 페이지에서는 첨부파일 만들기, 사용자가 첨부파일을 열 때 권장되는 작업, 학생 제출물 작업에 관한 구현 세부정보를 설명합니다. 이러한 요청을 할 때는 첨부파일 관련 매개변수 를 제공해야 할 수 있습니다.

첨부파일 만들기

적절한 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 쿼리 매개변수가 포함됩니다.
부가기능 개발자는 이러한 4개의 ID를 사용하여 학생 과제물을 가져옵니다. courses.courseWork.addOnAttachments.studentSubmissions 엔드포인트를 사용하여 학생 제출물에 관한 정보를 가져오거나 수정합니다.

제출 상태 감지

GET 요청을 courses.courseWork.addOnAttachments.studentSubmissions 엔드포인트에 실행하여 특정 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 값이 양수여야 합니다.
부가기능이 첨부파일의 원래 작성자여야 합니다.

이미 생성된 AddOnAttachment의 maxPoints 값을 수정하려면 addOnAttachments 엔드포인트에 PATCH 요청을 실행하면 됩니다.

성적을 설정해야 하는 경우

성적을 Google 클래스룸에 패스백하는 시점을 선택할 수 있습니다. 중요한 차이점은 교사만 성적을 수정할 수 있으므로 교사의 사용자 인증 정보를 저장할지 여부를 선택하는 것입니다.

Google 클래스룸에 성적을 전달할 수 있는 두 가지 부가기능 순간 이 있습니다. 학생이 과제를 완료할 때 또는 교사가 학생 과제물 검토 iframe에서 학생의 과제물을 열 때입니다.

학생이 과제를 완료할 때 성적을 설정하려면 교사의 오프라인 사용자 인증 정보를 저장한 다음 학생이 과제를 완료할 때 이를 가져와서 사용하여 성적을 수정해야 합니다. 이 메서드는 다음과 같은 잠재적 이점을 제공합니다.

원활한 성적 업데이트를 제공합니다. 교사는 클래스룸 UI에 성적이 채워지도록 특별한 조치를 취할 필요가 없습니다.
과제를 통해 수업의 진행 상황에 관한 실시간 통계를 제공합니다. 학생이 첨부파일을 완료할 때 성적을 설정하면 교사는 모든 제출물을 열지 않고도 학생의 이해도를 파악할 수 있습니다.

이 접근 방식은 성적 동기화에 비동기식 접근 방식 도 허용합니다. AddOnAttachmentStudentSubmission 엔드포인트를 주기적으로 폴링하여 학생이 과제물을 제출한 시점을 감지할 수 있습니다. 제출된 경우 저장된 사용자 인증 정보를 사용하여 제출물의 성적을 설정합니다.

학생 세션 중에 교사의 사용자 인증 정보를 로드하지 않으려면 교사가 학생 과제물 검토 iframe에서 학생의 제출물을 로드할 때 활성 교사의 사용자 인증 정보를 사용할 수 있습니다. 하지만 클래스룸 UI의 성적이 실시간으로 업데이트되지 않고 교사가 모든 제출물의 학생 과제물 검토 iframe을 열어야 하므로 특히 원활한 사용자 환경을 제공하지 못할 수 있습니다.

과제 성적 변경 감지

교사는 과제가 생성된 후 클래스룸에서 성적 설정을 수정할 수 있습니다. 이러한 수정에는 다음이 포함될 수 있습니다.

할당된 점수 값 변경
과제의 maxPoints 값 변경
과제를 채점해야 하는지 여부 변경

과제의 현재 채점 설정을 보려면 a GET 요청을 courses.courseWork 엔드포인트에 전송하는 것이 좋습니다. 응답에는 현재 maxPoints 값이 포함됩니다. 채점되지 않은 과제의 maxPoints 값은 null 또는 0입니다.

성적을 클래스룸에 패스백한 경우 courses.courseWork.addOnAttachments.studentSubmissions 엔드포인트를 사용하여 부가기능 첨부파일의 성적을 가져오거나 변경합니다. 성적 값은 pointsEarned 필드를 사용하여 설정됩니다. 제품에서 교사가 특정 활동의 학생 점수를 수정할 수 있는 경우 이 값을 확인하고 필요한 경우 업데이트하는 것이 좋습니다.