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 トピックを設定するには、次の操作を行う必要があります。

  1. Cloud Pub/Sub の前提条件を満たしていることを確認します。
  2. Cloud Pub/Sub クライアントをセットアップする。
  3. Cloud Pub/Sub の料金を確認し、Developer Console プロジェクトの課金を有効にします。

  4. Cloud Pub/Sub トピックは、デベロッパー コンソール（最も簡単）、コマンドライン ツール（単純なプログラムによる使用）、または Cloud Pub/Sub API を使用して作成します。Cloud Pub/Sub ではトピックの数に制限があるため、1 つのトピックを使用してすべての通知を受信すると、アプリケーションの人気が高まってもスケーリングの問題が発生しません。

  5. Cloud Pub/Sub でサブスクリプションを作成して、通知の配信方法を Cloud Pub/Sub に指示します。

  6. 最後に、プッシュ通知を登録する前に、トピックにパブリッシュする権限をプッシュ通知サービス アカウント（classroom-notifications@system.gserviceaccount.com）に付与する必要があります。

注: Cloud Pub/Sub トピックにパブリッシュする権限を Push Notifications サービス アカウントに付与すると、デベロッパー コンソール プロジェクトからリクエストを送信できるユーザーは、トピックが存在することを確認して、そのトピックへの通知を登録できるようになります。多くのアプリケーションでは OAuth クライアント ID がクライアント側に保存されるため、エンドユーザーが Developer Console プロジェクトからリクエストを送信できる場合があります。これに該当し、エンドユーザーが 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 が含まれます。この ID は registrations.delete() とともに使用して、通知の登録を解除できます。