添付ファイルを操作する

このページでは、アタッチメントの作成に関する実装の詳細、ユーザーがアタッチメントを開いたときの推奨アクション、生徒の提出物の操作について説明します。これらのリクエストを行う際は、アタッチメント関連のパラメータ を指定する必要がある場合があります。

アタッチメントを作成する

アタッチメントを作成するには、適切な 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 を表示します。
  • それ以外の場合、このアタッチメントは別のストリーム アイテムまたはコースからコピーされたものである必要があります。このシナリオに関する 推奨事項については、コピーされたコンテンツの処理ガイドをご覧ください。

生徒の提出物の詳細

一般的な提出ワークフローは次の手順で行われます。

  1. 生徒が studentViewUri を起動してアクティビティを完了します。
  2. アドオンは、生徒の認証情報を使用して getAddOnContext メソッドから submissionId を取得します。
  3. submissionId と attachmentId は、生徒の課題の一意の識別子としてアドオン デベロッパーによって保存されます。教師が Classroom で課題をコピーした場合、これらの 2 つのパラメータの複合キーを使用して、コピーされた課題に新しいアタッチメントを表示できます。詳しくは、コピーされたコンテンツに関する ページをご覧ください。
  4. 生徒の課題を確認したい教師が studentWorkReviewUri を起動します。リクエストには、courseId、itemId、itemType、attachmentId、submissionId のクエリ パラメータが含まれます。
  5. アドオン デベロッパーは、これらの 4 つの ID を使用して生徒の課題を取得します。the courses.courseWork.addOnAttachments.studentSubmissions エンドポイントを使用して、生徒の提出物に関する情報を 取得または変更します。

提出ステータスを検出する

GET リクエストを courses.courseWork.addOnAttachments.studentSubmissions エンドポイントに発行して、特定の submissionId の詳細を取得します。AddOnAttachmentStudentSubmission オブジェクトが返されます。このオブジェクトには、提出物の成績（pointsEarned）と現在のステータス（postSubmissionState）が含まれています。提出ステータスには、次のいずれかの値を指定できます。

  • NEW: 生徒が提出物にアクセスしたことがない場合。
  • CREATED: 生徒が提出物を作成したが、まだ提出していない場合。
  • TURNED_IN: 生徒が課題を教師に提出した場合。
  • RETURNED: 教師が生徒に提出物を返却した場合。
  • RECLAIMED_BY_STUDENT: 生徒が課題の提出を取り消した場合。

このエンドポイントを使用して、アドオンでの生徒の課題のステータスを検出します。返されたステータスに応じて、生徒に提供されるビューやオプションを調整できます。次のような機能が対象となります。

  • アドオン内で課題の提出ステータスを表示する。これにより、生徒は混乱を避け、誤って課題を提出し忘れることを防ぐことができます。
  • 提出物の編集権限を制限する。課題のステータスが CREATED または RECLAIMED_BY_STUDENT の場合、生徒は提出物を編集できることがあります。課題のステータスが TURNED_IN または RETURNED の場合、生徒は提出物を編集できないことがあります。

成績と複数のアタッチメント

単一の課題の成績を設定するために使用できるアドオン アタッチメントは 1 つだけです。 教師が maxPoints 値を提供するアクティビティ タイプのアタッチメントを複数作成した場合、最初のそのようなアタッチメントのみが課題の成績を設定できます。アタッチメントの成績の受け渡しを無効にするには、maxPoints 値を設定しないか、ゼロに設定します。

提出物の成績を設定する

courses.courseWork.addOnAttachments.studentSubmissions エンドポイントに PATCH リクエストを送信して、生徒の提出物を変更できます。リクエスト本文には、変更された値を含む 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 またはゼロです。

Classroom に成績を渡した場合は、courses.courseWork.addOnAttachments.studentSubmissions エンドポイントを使用して、アドオン アタッチメントの成績を取得または変更します。成績の値は pointsEarned フィールドを使用して設定されます。教師が特定のアクティビティの生徒のスコアを編集できる場合は、この値を確認し、必要に応じて更新することを検討してください。