このページは Cloud Translation API によって翻訳されました。

Classroom API でのプッシュ通知

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

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

Classroom のプッシュ通知の概要

Classroom API プッシュ通知機能を使用すると、Classroom API を使用するアプリケーションで、Classroom でデータが変更されたときに通知を受け取るよう登録できます。通知は、通常は変更から数分以内に Cloud Pub/Sub トピックに配信されます。

プッシュ通知を受信するには、次の操作を行う必要があります。Cloud Pub/Sub トピックを設定するそのトピックの名前を登録する適切な場合フィード通知

このドキュメントで使用する主なコンセプトの定義は次のとおりです。

「宛先」は、通知が送信される場所です。
フィードは、サードパーティアプリが登録できる通知タイプです。（「コース 1234 の名 ster の変更」など）。
「登録」は、特定のフィードから宛先に通知を配信するための、Classroom API への指示です。

フィードの登録を作成すると、その登録が期限切れになるまで、その登録の Cloud Pub/Sub トピックがそのフィードから通知を受信します。登録は 1 週間有効ですが、有効期限を切れる前に、registrations.create() に対して同じリクエストを送信することで、いつでも延長できます。

Cloud Pub/Sub トピックは、登録の作成時に指定した認証情報で表示できるリソースに関する通知のみを受け取ります。たとえば、ユーザーがアプリから権限を取り消した場合、または教師として削除された場合は、通知の時間が長くなります。

フィードのタイプ

Classroom API には現在、次の 3 種類のフィードがあります。

各ドメインには、ドメインの名 ro の変更フィードがあり、生徒と教師がそのドメインのコースに参加したり退出したりしたときに、その旨が通知されます。
各コースには、コース名 ster の変更フィードがあり、生徒と教師がそのコースに参加したり退出したりしたときに通知が送られます。
各コースのコース課題の変更（コース）には、コースの課題または生徒の提出物のオブジェクトが作成または変更されたときの通知が表示されます。

Cloud Pub/Sub トピックの設定

通知は Cloud Pub/Sub トピックに配信されます。Cloud Pub/Sub から、ウェブフックまたはサブスクリプションエンドポイントのポーリングによって通知を受信できます。

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

Cloud Pub/Sub の前提条件を満たしていることを確認してください。
Cloud Pub/Sub クライアントを設定します。
Cloud Pub/Sub の料金を確認し、Developer Console プロジェクトに対する課金を有効にします。
コマンドラインツールを使用して、Play 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 トピックへの公開権限を付与すると、Developer Console プロジェクトからリクエストを送信したユーザーは、その存在を確認して登録 101}通知を受け取ります。多くのアプリケーションは、クライアント側に 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）と、送信される通知に関するデータを表示するために必要なスコープを含める必要があります。

名 ster の変更フィードの場合、これは、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 でエンコードされ、次のものが含まれます。

変更されたリソースを含むコレクションの名前。名 ster の変更に関する通知には、courses.students または courses.teachers を指定します。コースの課題の変更の場合は、courses.courseWork または courses.courseWork.studentSubmissions を指定します。
変更されたリソースの ID（地図を使用）。このマップは、引数を適切なリソースの get メソッドと一致させるように設計されています。名 ster の変更に関する通知では、courseId フィールドと userId フィールドが入力され、変更せずに courses.students.get() に送信できます。または、courses.teachers.get() にアクセスしてください。同様に、courses.courseWork コレクションに変更を加えると、courseId フィールドと id フィールドが次のように変更されます。そのまま変更して courses.courseWork.get() に送信できます。courses.courseWork.studentSubmissions コレクションを変更すると、courseId、courseWorkId、 courses.courseWork.studentSubmissions.get() にそのまま送信できる id フィールド。

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

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

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