このページでは、添付ファイルの作成、ユーザーが添付ファイルを開いた場合の推奨アクション、生徒の提出物の操作に関する実装の詳細について説明します。これらのリクエストを行う際には、添付ファイル関連のパラメータを指定する必要がある場合があります。
アタッチメントの作成
適切な courses.*.addOnAttachments.create エンドポイントに CREATE リクエストを発行して、添付ファイルを作成します。リクエストの本文には AddOnAttachment のインスタンスを含める必要があります。
添付ファイルを作成する際は、次のフィールドが必須です。
title: アタッチメントの文字列名。teacherViewUri: 添付ファイルの教師用ビューの URI。studentViewUri: 添付ファイルの生徒用ビューの URI。studentWorkReviewUri: 教師が添付ファイルで生徒の課題を確認するための URI。このフィールドは、アクティビティ タイプの添付ファイルにのみ必要です。
次のオプション フィールドを含めることができます。
- 添付ファイルの期限を指定する場合は、
dueDateとdueTime。 maxPoints: アタッチメントの最大グレード。成績のパスバックをサポートする場合は、ゼロ以外の値にする必要があります。アクティビティ タイプのアタッチメントにのみ適用されます。
これらのフィールドの詳細については、AddOnAttachment リソース リファレンスをご覧ください。
ユーザー認証情報とロールを検証する
生徒用ビューの iframe、生徒の提出物レビューの iframe、教師用ビューの iframe はすべて、Classroom の課題を変更するのではなく、ユーザーにコンテンツを表示することを目的としています。これらのビューのいずれかが開いた場合は、次のことを検討してください。
- ユーザーの OAuth 認証情報を取得します。
itemTypeに基づいてcourseWork.getAddOnContext、courseWorkMaterials.getAddOnContext、またはannouncements.getAddOnContextリクエストを行い、ユーザーロールを検証します。- レスポンスを調べて、
TeacherContextまたはStudentContextが存在するかどうかを確認します。コース内のユーザーの役割に対応する 1 つのみが返されます。 - 現在のユーザーが生徒で、
itemTypeがcourseWorkの場合、レスポンスのsubmissionIdを生徒の課題とともに記録します。submissionIdsはアドオンの iframe 間で一致し、成績を返したり、採点ツールで生徒の課題を教師に表示したりするために必要です。 attachmentIdがアドオンにすでに認識されている場合は、適切な添付ファイル UI を表示します。- それ以外の場合、この添付ファイルは別のストリーム アイテムまたはコースからコピーされたものである必要があります。このシナリオに関する推奨事項については、コピーされたコンテンツの処理ガイドをご覧ください。
生徒の提出物の詳細
一般的な送信ワークフローは次の手順で行われます。
- 生徒が
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値が必要です。 - アドオンが添付ファイルの元の作成者である必要があります。
また、addOnAttachments エンドポイントに PATCH リクエストを発行することで、作成済みの AddOnAttachment の maxPoints 値を変更することもできます。
成績を設定するタイミング
成績を Google Classroom に返却するタイミングは、ある程度選択できます。重要なのは、教師の認証情報を保存するかどうかです。成績を変更できるのは教師のみです。
Google Classroom に成績を渡すタイミングは、2 つのアドオンのタイミングがあります。生徒が課題を完了したとき、または教師が生徒の課題を生徒の課題のレビュー用 iframe で開いたときです。
生徒が課題を完了したときに成績を設定する場合は、教師のオフライン認証情報を保存し、生徒が課題を完了したときに取得して使用し、成績を変更する必要があります。この方法には次のようなメリットがあります。
- シームレスなグレード更新を提供します。教師が Classroom の UI に成績を入力するために特別な操作を行う必要はありません。
- クラスの課題の進捗状況をリアルタイムで把握できます。生徒が添付ファイルを完成させると、教師は課題に点数を設定できるため、すべての提出物を開かなくても生徒の理解度を把握できます。
なお、このアプローチでは、成績の同期に非同期アプローチも使用できます。生徒が課題を提出したタイミングを検出するために、AddOnAttachmentStudentSubmission エンドポイントを定期的にポーリングすることがあります。提出されたら、保存された認証情報を使用して提出の成績を設定します。
生徒のセッション中に教師の認証情報を読み込まない場合は、生徒の提出物のレビュー用 iframe で生徒の提出物を読み込むときに、有効な教師の認証情報を使用できます。ただし、この方法では、Classroom UI の成績がリアルタイムで更新されず、教師がすべての提出物の生徒の課題のレビュー iframe を開く必要があるため、ユーザー エクスペリエンスが特にスムーズになるとは限りません。
課題の成績の変化を検出する
課題の作成後に、教師が Classroom で成績の設定を編集することは可能です。このような編集には、次のようなものがあります。
- 割り当てられたポイントの値を変更する。
- 割り当ての
maxPoints値を変更する。 - 課題を採点するかどうかを変更する。
課題の現在の採点設定を確認するには、courses.courseWork エンドポイントに GET リクエストを送信することをおすすめします。レスポンスには現在の maxPoints 値が含まれます。採点されていない課題の maxPoints 値は null または 0 です。
Classroom に成績を返した場合は、courses.courseWork.addOnAttachments.studentSubmissions エンドポイントを使用して、アドオンの添付ファイルの成績を取得または変更します。グレード値は pointsEarned フィールドを使用して設定されます。教師が特定の課題の生徒のスコアを編集できるプロダクトの場合は、この値を確認し、必要に応じて更新することを検討してください。