このページでは、添付ファイルの作成と生徒の提出物の操作に関する実装の詳細について説明します。これらのリクエストを行う際に、アタッチメント関連のパラメータの指定が必要になる場合があります。
アタッチメントの作成
適切な courses.*.addOnAttachments.create エンドポイントに CREATE リクエストを送信してアタッチメントを作成します。リクエスト本文に AddOnAttachment のインスタンスを含める必要があります。
アタッチメントを作成するには、次のフィールドが必要です。
title: アタッチメントの文字列名。teacherViewUri: 添付ファイルの教師ビューの URI。studentViewUri: アタッチメントの生徒ビューの URI。studentWorkReviewUri: 添付ファイルに対する生徒の提出物を確認できる教師の URI。このフィールドは、アクティビティ タイプのアタッチメントの場合にのみ必要です。
必要に応じて、次の省略可能なフィールドを含めることができます。
- 添付ファイルの期限を指定する場合、
dueDateとdueTime。 maxPoints: アタッチメントの最高成績。成績の送信をサポートする場合は、ゼロ以外の値を指定する必要があります。アクティビティ タイプのアタッチメントにのみ適用されます。
これらのフィールドの詳細については、AddOnAttachment リソース リファレンスをご覧ください。
生徒による提出の詳細
一般的な提出ワークフローは次のとおりです。
- 生徒が
studentViewUriを起動してアクティビティを完了します。 - アドオンは、学生の認証情報を使用して
getAddOnContextメソッドからsubmissionIdを取得します。 submissionIdとattachmentIdは、アドオン デベロッパーによって生徒の提出物の一意の識別子として保存されます。教師が Classroom に課題をコピーした場合、これら 2 つのパラメータの複合キーを使用して、コピーした課題に新しい添付ファイルを表示できます。詳しくは、コピーされたコンテンツに関するページをご覧ください。- 生徒の提出物の確認に興味がある教師が
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の場合、生徒は提出物を編集できないことがあります。
成績と複数の添付ファイル
1 つの課題の成績の設定に使用できるアドオン アタッチメントは 1 つだけです。教師が maxPoints 値を指定するアクティビティ タイプの添付ファイルを複数作成した場合、課題の成績を設定できるのは最初の添付ファイルのみとなります。添付ファイルの成績の送信を無効にするには、maxPoints 値を未設定のままにするか、ゼロに設定します。
提出物の成績を設定する
生徒の提出物を変更するには、PATCH リクエストを courses.courseWork.addOnAttachments.studentSubmissions エンドポイントに送信します。リクエストの本文には、値を変更した AddOnAttachmentStudentSubmission のインスタンスを含める必要があります。提出物の成績を変更するには、pointsEarned フィールドを設定します。pointsEarned で渡された値は仮成績になり、教師は Classroom UI でその成績を確認できます。教師は生徒に課題を返却する前に
仮成績を変更できます教師に成績を表示する方法について詳しくは、Classroom の UI での評価の概要をご覧ください。
pointsEarned で成績を設定できるのは、次の条件を満たす場合のみです。
- アタッチメントには正の
maxPoints値が必要です。 - 添付ファイルの元の作成者がアドオンである必要があります。
作成済みの AddOnAttachment の maxPoints 値を変更するには、addOnAttachments エンドポイントに PATCH リクエストを発行します。
どのような場合に成績を設定するか
Google Classroom に成績を返却するタイミングは、ユーザーが選択できます。大きく異なるのは、教師の認証情報を保存するかどうかです。成績を変更できるのは教師だけです。
Google Classroom に成績を渡すアドオンとして次の 2 つがあります。それは、生徒が課題を完了したタイミングと、教師が Student Work Review iframe で生徒の提出物を開いた場合です。
生徒の課題の完了時に成績を設定する場合は、教師のオフライン認証情報を保存し、生徒が課題を完了したときに成績を取得して、成績を変更する必要があります。この方法には、次のようなメリットがあります。
- 成績をシームレスに更新。教師は、Classroom UI に成績を入力するために特別な操作を行う必要はありません。
- 課題を通じてクラスの進捗状況をリアルタイムで分析できます。生徒が添付ファイルに記入する際に成績を設定することで、教師はすべての提出物を開くことなく、生徒の理解度を確認できます。
このアプローチでは、非同期アプローチで同期を評価することもできます。AddOnAttachmentStudentSubmission エンドポイントを定期的にポーリングして、生徒が課題を提出したことを検出することもできます。課題を提出したら、保存されている認証情報を使用して課題の成績を設定します。
生徒のセッション中に教師の認証情報を読み込まない場合は、アクティブな教師の認証情報を使用して、生徒の提出物の確認 iframe で生徒の提出物を読み込むことができます。ただし、Classroom UI の成績はリアルタイムで更新されず、教師はすべての提出物の Student Work Review iframe を開く必要があるため、特にスムーズなユーザー エクスペリエンスは得られない場合があります。
課題の成績の変更を検出する
教師は課題の作成後に Classroom で成績の設定を編集できますたとえば、次のような編集が該当します。
- 割り当てられる点数を変更する。
- 割り当ての
maxPoints値の変更。 - 課題を採点するかどうかを変更する。
課題の現在の採点設定を表示するには、GET リクエストを courses.courseWork エンドポイントに送信することをおすすめします。レスポンスには現在の maxPoints 値が含まれます。採点なしの課題の maxPoints 値は null かゼロです。
Classroom に成績を返却した場合は、courses.courseWork.addOnAttachments.studentSubmissions エンドポイントを使用して、アドオン添付ファイルの成績を取得または変更します。成績の値は pointsEarned フィールドを使用して設定されます。プロダクトで教師が特定のアクティビティの生徒のスコアを編集できる場合は、この値を確認し、必要に応じて更新することを検討してください。