このページでは、添付ファイルの作成と生徒の提出物の操作の実装の詳細について説明します。これらのリクエストを行う際に、アタッチメント関連のパラメータの指定が必要になることがあります。
アタッチメントの作成
アタッチメントを作成するには、CREATE リクエストを適切な courses.*.addOnAttachments.create エンドポイントに発行します。リクエストの本文には AddOnAttachment のインスタンスを含める必要があります。
添付ファイルを作成する際は、次のフィールドが必要です。
title: アタッチメントの文字列名。teacherViewUri: アタッチメントの教師用のビューの URI。studentViewUri: アタッチメントの生徒用のビューの URI。studentWorkReviewUri: 添付ファイルでの生徒の提出物を教師が表示する URI。このフィールドは、アクティビティ タイプの添付ファイルにのみ必須です。
次のオプション フィールドの一部を含めることをおすすめします。
- アタッチメントの期限を指定する場合は、
dueDateとdueTime。 maxPoints: 添付ファイルの最大成績。成績の送信をサポートする場合は、0 以外の値を指定する必要があります。アクティビティ タイプの添付ファイルにのみ適用されます。
これらのフィールドの詳細については、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 の詳細を取得します。提出物の成績（pointsEarned）と現在のステータス（postSubmissionState）を含む AddOnAttachmentStudentSubmission オブジェクトを受け取ります。提出ステータスは次のいずれかの値になります。
NEW: 生徒が提出物にアクセスしたことがない場合。CREATED: 生徒が提出物を作成したものの、まだ提出していない場合。TURNED_IN: 生徒が教師に課題を提出済みの場合。RETURNED: 教師が提出物を生徒に返却した場合。RECLAIMED_BY_STUDENT: 生徒が課題を「提出を取り消した」場合。
このエンドポイントを使用して、アドオンでの生徒の課題の状態を検出します。その後、返された状態に応じて、生徒に表示されるビューまたはオプションを調整できます。たとえば、次のような機能があります。
- アドオン内の課題の提出状況を表示する。これにより、生徒は混乱を招かなくなり、誤って課題の提出に失敗することがなくなります。
- 投稿の編集権限を制限する。課題のステータスが
CREATEDまたはRECLAIMED_BY_STUDENTの場合、生徒は提出物の編集が許可されている場合があります。課題のステータスがTURNED_INまたはRETURNEDの場合、生徒は提出物を編集できない可能性があります。
成績と複数の添付ファイル
1 つの課題の成績を設定できるアドオンの添付ファイルは 1 つのみです。教師が maxPoints 値を提供するアクティビティ タイプのアタッチメントを複数作成した場合は、最初の添付ファイルのみが課題の成績を設定できます。maxPoints の値を未設定のままにするか、0 に設定して、添付ファイルの成績の送信を無効にします。
提出物の成績を設定する
生徒の提出物を変更するには、PATCH リクエストを courses.courseWork.addOnAttachments.studentSubmissions エンドポイントに送信します。リクエストの本文には、変更した値を持つ AddOnAttachmentStudentSubmission のインスタンスを含める必要があります。提出物の成績を変更するには、pointsEarned フィールドを設定します。
pointsEarned で渡された値は仮成績となり、Classroom UI で教師に表示されます。教師は課題を生徒に返却する前に
仮成績を変更できます教師への成績の表示方法の詳細については、Classroom UI での採点の概要をご覧ください。
pointsEarned で成績を設定できるのは、次の条件を満たしている場合のみです。
- アタッチメントには正の
maxPoints値を指定する必要があります。 - アドオンは添付ファイルの元の作成者である必要があります。
また、addOnAttachments エンドポイントに PATCH リクエストを発行することで、作成済みの AddOnAttachment の maxPoints 値を変更することもできます。
成績を設定するタイミング
成績を Google Classroom にいつ返すかは、管理者が選択できます。成績を変更できるのは教師のみであるため、教師の認証情報を保存するかどうかが重要な違いです。
Google Classroom に成績を渡すタイミングには、生徒が課題を完了したときと、教師が [生徒の提出物の確認] iframe で生徒の提出物を開いたときがあります。
生徒が課題を完了したら、教師のオフライン認証情報を保存し、生徒が課題を完了したら、それを取得して使用し、成績を変更する必要があります。この方法には、次のような利点があります。
- 成績をシームレスに更新できる。教師は Classroom の UI に成績を表示するために特別な操作を行う必要はありません。
- 課題を通じてクラスの進捗状況をリアルタイムで分析します。生徒が添付ファイルを完了したときに成績を設定すると、教師はすべての提出物を開くことなく、生徒の理解度を確認できます。
この方法では、非同期のアプローチで採点の同期も可能になります。生徒が課題を提出したことを検出するために、AddOnAttachmentStudentSubmission エンドポイントを定期的にポーリングできます。課題を送信したら、保存されている認証情報を使用して提出物の成績を設定します。
生徒セッション中に教師の認証情報を読み込まない場合は、アクティブな教師の認証情報を使用して、生徒の提出物の確認 iframe で生徒の提出物を読み込みます。ただし、Classroom UI の成績はリアルタイムでは更新されず、教師はすべての提出物の Student Work Review iframe を開く必要があるため、ユーザー エクスペリエンスが特にスムーズになるとは限りません。
課題の成績の変化を検出する
教師は課題の作成後に Classroom で成績の設定を編集できますたとえば、次のような編集を行います。
- 割り当てられた点数を変更する。
- 割り当ての
maxPoints値の変更。 - 課題を採点するかどうかの変更。
課題の現在の成績設定を確認するには、GET リクエストを courses.courseWork エンドポイントに送信することをおすすめします。レスポンスには、現在の maxPoints 値が含まれます。採点なしの課題の maxPoints 値は null または 0 です。
成績を Classroom に戻した場合は、courses.courseWork.addOnAttachments.studentSubmissions エンドポイントを使用して、アドオンの添付ファイルの成績を取得または変更します。成績の値は、pointsEarned フィールドを使用して設定します。プロダクトで教師が特定のアクティビティの生徒のスコアを編集できる場合は、この値を確認し、必要に応じて更新することを検討してください。