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 から、ウェブフックで通知を受け取るか、サブスクリプションエンドポイントをポーリングして通知を受け取ることができます。

Cloud Pub/Sub トピックを設定するには、次の操作を行う必要があります。

Cloud Pub/Sub の前提条件を満たしていることを確認します。
Cloud Pub/Sub クライアントを設定します。
Cloud Pub/Sub の料金を確認し、Developer Console プロジェクトの課金を有効にします。
Cloud Pub/Sub トピックは、デベロッパーコンソール（最も簡単）、コマンドラインツール（単純なプログラムによる使用）、または Cloud Pub/Sub API を使用して作成します。Cloud Pub/Sub ではトピックの数に制限があるため、1 つのトピックを使用してすべての通知を受信すると、アプリケーションの人気が高まってもスケーリングの問題が発生しません。
Cloud Pub/Sub でサブスクリプションを作成して、通知の配信方法を Cloud Pub/Sub に指示します。
最後に、プッシュ通知を登録する前に、トピックにパブリッシュする権限をプッシュ通知サービスアカウント（classroom-notifications@system.gserviceaccount.com）に付与する必要があります。

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

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

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

承認

Classroom API のすべての呼び出しと同様に、registrations.create() の呼び出しは承認トークンで承認される必要があります。この認証トークンには、プッシュ通知スコープ（https://www.googleapis.com/auth/classroom.push-notifications）と、送信される通知に関するデータを表示するために必要なスコープを含める必要があります。

ロースター変更フィードの場合、これは Rosters スコープまたは（理想的には）その読み取り専用バリアント（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 コレクションの変更では、courseId フィールドと id フィールドが入力され、変更を加えず courses.courseWork.get() に送信できます。また、courses.courseWork.studentSubmissions コレクションの変更では、courseId、courseWorkId、id フィールドが入力され、変更を加えず courses.courseWork.studentSubmissions.get() に送信できます。

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

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

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