このページでは、添付ファイルの作成と生徒の提出物の操作の実装の詳細について説明します。これらのリクエストを行う際に、アタッチメント関連のパラメータの指定が必要になることがあります。
アタッチメントの作成
適切な 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エンドポイントを使用して、生徒の提出物に関する情報を取得または変更します。
送信状態を検出する
特定の submissionId の詳細を取得するには、courses.courseWork.addOnAttachments.studentSubmissions エンドポイントに GET リクエストを送信します。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 に渡すタイミングは、生徒が課題を完了したときと、教師が生徒の課題の iframe で生徒の課題を開いたときの2 つです。
生徒が課題を完了したときに成績を設定するには、教師のオフライン認証情報を保存し、生徒が課題を完了したときにその認証情報を取得して成績を変更する必要があります。この方法には、次のような利点があります。
- 成績をシームレスに更新できます。教師は Classroom の UI に成績を表示するために特別な操作を行う必要はありません。
- 課題の進捗状況に関するリアルタイムの分析情報をクラスに提供します。生徒が添付ファイルを完了したときに成績を設定すると、教師はすべての提出物を開くことなく、生徒の理解度を確認できます。
このアプローチでは、成績の同期に非同期アプローチも使用できます。AddOnAttachmentStudentSubmission エンドポイントを定期的にポーリングして、生徒が課題を提出したタイミングを検出できます。送信されたら、保存されている認証情報を使用して送信の成績を設定します。
生徒のセッション中に教師の認証情報を読み込みたくない場合は、生徒の提出物の確認用 iframe で生徒の提出物を読み込むときに、アクティブな教師の認証情報を使用できます。ただし、Classroom UI の成績はリアルタイムで更新されず、教師はすべての提出物の生徒の課題レビューの iframe を開く必要があるため、特にスムーズなユーザー エクスペリエンスが提供されない可能性があります。
課題の成績の変化を検出する
教師は、課題の作成後に Classroom で成績の設定を編集できます。たとえば、次のような編集を行います。
- 割り当てられたポイント値の変更。
- 割り当ての
maxPoints値を変更する。 - 課題の採点を行うかどうかを変更する。
課題の現在の採点設定を確認するには、courses.courseWork エンドポイントに GET リクエストを送信することをおすすめします。レスポンスには、現在の maxPoints 値が含まれます。採点されていない課題には、null またはゼロの maxPoints 値が設定されます。
採点を Classroom に渡した場合は、courses.courseWork.addOnAttachments.studentSubmissions エンドポイントを使用して、アドオンの添付ファイルの採点を取得または変更します。成績の値は、pointsEarned フィールドを使用して設定します。プロダクトで教師が特定のアクティビティの生徒のスコアを編集できる場合は、この値を確認し、必要に応じて更新することを検討してください。