첨부파일과 상호작용

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

연결 만들기

적절한 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를 표시합니다.
  • 그렇지 않으면 이 첨부파일이 다른 스트림 항목이나 강의에서 복사된 것입니다. 이 시나리오에 관한 권장사항은 복사된 콘텐츠 처리 가이드를 참고하세요.

학생 제출물 세부정보

일반적인 제출 워크플로는 다음 단계를 따릅니다.

  1. 학생이 studentViewUri를 실행하여 활동을 완료합니다.
  2. 부가기능은 학생 사용자 인증 정보를 사용하여 getAddOnContext 메서드에서 submissionId를 가져옵니다.
  3. submissionId 및 attachmentId는 부가기능 개발자가 학생의 과제의 고유 식별자로 저장합니다. 교사가 클래스룸에서 과제를 복사하는 경우 이 두 매개변수의 복합 키를 사용하여 복사된 과제에 새 첨부파일을 표시할 수 있습니다. 자세한 내용은 복사된 콘텐츠 페이지를 참고하세요.
  4. 학생 과제물을 검토하고자 하는 교사가 studentWorkReviewUri를 실행합니다. 요청에는 courseId, itemId, itemType, attachmentId, submissionId 쿼리 매개변수가 포함됩니다.
  5. 부가기능 개발자는 이 네 가지 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의 성적 개요를 참고하세요.

다음이 모두 true인 경우에만 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 필드를 사용하여 설정됩니다. 제품에서 교사가 특정 활동에 대한 학생의 점수를 수정할 수 있는 경우 이 값을 확인하고 필요한 경우 업데이트해 보세요.