Classroom API でのプッシュ通知

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 トピックは、Play Console で簡単に作成します。作成には、コマンドラインツールを使用する（プログラムで簡単に使用できる）か、Cloud Pub/Sub API を使用します。Cloud Pub/Sub では、許可されるトピック数が限られているため、すべての通知を受信するために 1 つのトピックを使用すれば、アプリケーションの人気が高まった場合でもスケーリングの問題が生じないことに注意してください。
Cloud Pub/Sub でサブスクリプションを作成して、Cloud Pub/Sub に通知の配信方法を指示します。
最後に、プッシュ通知に登録する前に、トピックに公開するためのプッシュ通知サービスアカウント（classroom-notifications@system.gserviceaccount.com）権限を付与する必要があります。

注: プッシュ通知サービスアカウントに Cloud Pub/Sub トピックへの公開権限を付与すると、Developer Console プロジェクトからリクエストを行うことができるユーザーは、そのプロジェクトが存在することを確認し、通知に登録できるようになります。多くのアプリケーションは OAuth クライアント ID をクライアントサイドに保存しているため、エンドユーザーは Developer Console プロジェクトからリクエストを送信できる可能性があります。これに該当し、エンドユーザーが不要な通知を Cloud Pub/Sub トピックに送信することや、プッシュ通知に使用する Cloud Pub/Sub トピックの名前を知っていることが心配な場合は、別の Developer Console プロジェクトからのプッシュ通知への登録を検討してください。

通知を受けるアプリケーションを登録する

Classroom API プッシュ通知サービスアカウントが公開できるトピックを用意したら、registrations.create() メソッドを使用して通知を登録できます。registrations.create() メソッドは、プッシュ通知のサービスアカウントが、指定された Cloud Pub/Sub トピックに到達できることを検証します。プッシュ通知サービスアカウントがトピックにアクセスできない場合、メソッドは失敗します（トピックが存在しない場合や、そのトピックに対する公開権限を付与していない場合など）。

承認

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 になります。
マップ内で変更されたリソースの識別子。このマップは、該当するリソースの get メソッドの引数と一致するように設計されています。名簿の変更に関する通知の場合、courseId フィールドと userId フィールドに値が設定されます。これらのフィールドを変更せずに courses.students.get() または courses.teachers.get() に送信できます。同様に、courses.courseWork コレクションの変更には courseId フィールドと id フィールドがあり、これらは変更せずに courseWorkIdcourses.courses{courses{courses{courses,students.get() に送信できる courseIdフィールドと id フィールドを持ちます。courses.courseWork.studentSubmissions.get()

通知のサンプルを次のコードスニペットに示します。

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

通知には registrationId メッセージ属性もあり、通知の原因となった登録の ID が含まれています。この属性を registrations.delete() で使用して、通知の登録を解除できます。