ユーザーが Classroom と Google Meet を使用している場合は、Google Meet コースの生徒の出席状況を確認する Apps Script クイックスタートをご覧ください。

Classroom API のプッシュ通知

Registrations コレクションのメソッドを使用して、Classroom でデータが変更されたときに通知を受け取ることができます。

この記事では、概念についての概要と、プッシュ通知の受信を開始する簡単な方法について説明します。

Classroom のプッシュ通知の概要

Classroom API のプッシュ通知機能を使用すると、Classroom でデータが変更されたときに、Classroom API を使用するアプリケーションが通知を登録できます。通知は、通常は変更後数分以内に 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 トピックを設定するには、次のようにします。

  1. Cloud Pub/Sub の前提条件を満たしていることを確認します。
  2. Cloud Pub/Sub クライアントを設定します。
  3. Cloud Pub/Sub の料金を確認し、デベロッパー コンソールのプロジェクトに対して課金を有効にします。

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

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

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

注: プッシュ通知サービス アカウントに Cloud Pub/Sub トピックに公開する権限を付与すると、Developer Console プロジェクトからリクエストを送れるユーザーは、その存在を認識して通知に登録できるようになります。多くのアプリケーションでは、OAuth クライアント ID をクライアント側に保存するため、エンドユーザーがデベロッパー コンソール プロジェクトからリクエストを行える可能性があります。これに該当する場合で、エンドユーザーが 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 でエンコードされ、次の内容が含まれます。

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

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

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