Registrations コレクションのメソッドを使用すると、Classroom のデータが変更されたときに通知を受け取ることができます。
この記事では、プッシュ通知の受信を開始する方法について、簡単な手順と概念的な概要を説明します。
Classroom のプッシュ通知の概要
Classroom API のプッシュ通知機能を使用すると、Classroom API を使用するアプリケーションで、Classroom のデータが変更されたときに通知を受け取ることができます。通知は、通常、変更から数分以内に Cloud Pub/Sub トピックに配信されます。
プッシュ通知を受け取るには、Cloud Pub/Sub トピックを設定し、通知の適切なフィードの登録を作成するときに、そのトピックの名前を指定する必要があります。
このドキュメントで使用されている主なコンセプトの定義は次のとおりです。
- 宛先は、通知が送信される場所です。
- フィードは、サードパーティ アプリケーションが登録できる通知の一種です。例: 「コース 1234 の名簿の変更」
- 登録とは、特定のフィードから宛先に通知を配信するよう Classroom API に指示することです。
フィードの登録を作成すると、その登録の Cloud Pub/Sub トピックは、有効期限が切れるまでそのフィードから通知を受け取ります。登録は 1 週間有効ですが、有効期限が切れる前に registrations.create() に同じリクエストを行うことで、いつでも延長できます。
Cloud Pub/Sub トピックは、登録の作成時に指定した認証情報で表示できるリソースに関する通知のみを受信します。たとえば、ユーザーがアプリの権限を取り消した場合や、教師として削除された場合、通知は配信されなくなります。
フィードのタイプ
Classroom API には次の 3 種類のフィードがあります。
- 各ドメインには、ドメインのクラス名簿の変更フィードがあります。このフィードは、そのドメインのコースに生徒や教師が参加したり、コースから離脱したりしたときに通知を公開します。
- 各コースには、コースの登録者変更フィードがあります。このフィードは、生徒や教師がコースに参加したりコースから離れたりしたときに通知を公開します。
- 各コースには、コースの課題の変更フィードがあります。このフィードは、コースの課題オブジェクトまたは生徒の提出物オブジェクトが作成または変更されたときに通知を公開します。
Cloud Pub/Sub トピックを設定する
通知は Cloud Pub/Sub トピックに配信されます。Cloud Pub/Sub から、Webhook で通知を受信するか、サブスクリプション エンドポイントをポーリングして通知を受信できます。
Cloud Pub/Sub トピックを設定するには、次の操作を行う必要があります。
- Cloud Pub/Sub の前提条件を満たしていることを確認します。
- Cloud Pub/Sub クライアントを設定する。
- Cloud Pub/Sub の料金を確認し、Developer Console プロジェクトの課金を有効にします。
デベロッパー コンソール（最も簡単）、コマンドライン ツール（簡単なプログラムでの使用）、または Cloud Pub/Sub API を使用して、Cloud Pub/Sub トピックを作成します。Cloud Pub/Sub ではトピックの数が制限されているため、1 つのトピックを使用してすべての通知を受信することで、アプリケーションが人気になった場合にスケーリングの問題が発生しないようにします。
Cloud Pub/Sub でサブスクリプションを作成して、Cloud Pub/Sub に通知の配信方法を指示します。
最後に、プッシュ通知に登録する前に、トピックにパブリッシュするプッシュ通知サービス アカウント（
classroom-notifications@system.gserviceaccount.com）の権限を付与する必要があります。
通知用にアプリケーションを登録する
Classroom API プッシュ通知サービス アカウントが公開できるトピックを作成したら、registrations.create() メソッドを使用して通知を登録できます。registrations.create() メソッドは、指定された Cloud Pub/Sub トピックに push 通知サービス アカウントからアクセスできることを検証します。プッシュ通知サービス アカウントがトピックにアクセスできない場合（トピックが存在しない場合や、そのトピックに対するパブリッシュ権限が付与されていない場合など）、このメソッドは失敗します。
承認
Classroom API へのすべての呼び出しと同様に、registrations.create() への呼び出しは、承認トークンで承認を受ける必要があります。この認証トークンには、プッシュ通知スコープ（https://www.googleapis.com/auth/classroom.push-notifications）と、送信される通知に関するデータを表示するために必要なスコープを含める必要があります。
- 名簿変更フィードの場合、これは名簿スコープまたは（理想的には）その読み取り専用バリアント（
https://www.googleapis.com/auth/classroom.rosters.readonlyまたはhttps://www.googleapis.com/auth/classroom.rosters）を意味します。 - コースの課題の変更フィードの場合、これはコースの課題スコープの「生徒」バージョン、または（理想的には）その読み取り専用バリアント（
https://www.googleapis.com/auth/classroom.coursework.students.readonlyまたはhttps://www.googleapis.com/auth/classroom.coursework.students）を意味します。
通知を配信するには、アプリケーションが、必要なスコープを持つ承認済みユーザーからの OAuth 認証情報を保持している必要があります。ユーザーがアプリの接続を解除すると、通知は停止します。なお、現在、この目的でドメイン全体の権限委任はサポートされていません。ドメイン全体の委任された権限のみを使用して通知を登録しようとすると、@MissingGrant エラーが発生します。
受け取るお知らせの種類
通知は JSON でエンコードされ、次の情報が含まれます。
- 変更されたリソースを含むコレクションの名前。シフト変更の通知の場合、これは
courses.studentsまたはcourses.teachersのいずれかです。コースの課題の変更の場合、これはcourses.courseWorkまたはcourses.courseWork.studentSubmissionsです。 - 変更されたリソースの ID（マップ内）。このマップは、適切なリソースの
getメソッドの引数と一致するように設計されています。名簿の変更に関する通知の場合、courseIdフィールドとuserIdフィールドが入力され、変更せずに courses.students.get() または courses.teachers.get() に送信できます。同様に、courses.courseWork コレクションの変更には、変更せずに courses.courseWork.get() に送信できるcourseIdフィールドとidフィールドが含まれます。また、courses.courseWork.studentSubmissions コレクションの変更には、変更せずに courses.courseWork.studentSubmissions.get() に送信できるcourseIdフィールド、courseWorkIdフィールド、idフィールドが含まれます。
次のコード スニペットは、通知のサンプルを示しています。
{
"collection": "courses.students",
"eventType": "CREATED",
"resourceId": {
"courseId": "12345",
"userId": "45678"
}
}
通知には registrationId メッセージ属性もあります。この属性には、通知の原因となった登録の識別子が含まれています。この識別子は registrations.delete() で使用して、通知の登録を解除できます。