Push-уведомления в API Класса

You can use the methods on the Registrations collection to receive notifications when data changes in Classroom.

This article provides a conceptual overview along with simple instructions on how to start receiving push notifications.

Обзор push-уведомлений в Classroom

Функция push-уведомлений API Classroom позволяет приложениям, использующим API Classroom, подписываться на уведомления об изменениях данных в Classroom. Уведомления доставляются в топик Cloud Pub/Sub , обычно в течение нескольких минут после изменения.

To receive push notifications, you need to set up a Cloud Pub/Sub topic and provide that topic's name when you create a registration for the appropriate feed of notifications.

Below are definitions of key concepts used in this documentation:

  • A destination is a place where notifications are sent.
  • A feed is a type of notifications that a third party application can subscribe to. For example, "roster changes for course 1234".
  • A registration is an instruction to the Classroom API to deliver notifications from a particular feed to a destination .

После создания регистрации для ленты новостей, тема Cloud Pub/Sub, к которой относится эта регистрация, будет получать уведомления от этой ленты до истечения срока её действия. Ваша регистрация действует неделю, но вы можете продлить её в любой момент до истечения срока действия, отправив запрос, идентичный запросу registrations.create() .

В вашу тему Cloud Pub/Sub поступают уведомления только о ресурсах, которые вы можете просматривать с помощью учетных данных, указанных при регистрации. Например, если пользователь отзывает разрешение на доступ к вашему приложению или удаляется из списка преподавателей, уведомления перестают доставляться.

Виды кормов

API Classroom предлагает три типа ленты новостей:

  • Each domain has a roster changes for domain feed, which exposes notifications when students and teachers join and leave courses in that domain.
  • Each course has a roster changes for course feed, which exposes notifications when students and teachers join and leave courses in that course.
  • Each course has a course work changes for course feed, which exposes notifications when any course work or student submission objects are created or modified in that course.

Настройте тему Cloud Pub/Sub.

Notifications are delivered to Cloud Pub/Sub topics. From Cloud Pub/Sub, you can receive notifications on a webhook, or by polling a subscription endpoint.

To set up a Cloud Pub/Sub topic, you need to do the following:

  1. Make sure you fulfill the Cloud Pub/Sub Prerequisites .
  2. Настройте клиент Cloud Pub/Sub .
  3. Review the Cloud Pub/Sub pricing , and enable billing for your Developer Console project.

  4. Создайте тему Cloud Pub/Sub в консоли разработчика (самый простой способ), с помощью инструмента командной строки (для простого программного использования) или с помощью API Cloud Pub/Sub . Обратите внимание, что Cloud Pub/Sub поддерживает только ограниченное количество тем , поэтому использование одной темы для получения всех уведомлений гарантирует отсутствие проблем с масштабированием, если ваше приложение станет популярным.

  5. Create a Subscription in Cloud Pub/Sub , to tell Cloud Pub/Sub how to deliver your notifications.

  6. Наконец, перед регистрацией для получения push-уведомлений необходимо предоставить учетной записи службы push-уведомлений ( classroom-notifications@system.gserviceaccount.com ) разрешение на публикацию уведомлений в вашей теме.

Зарегистрируйте свою заявку для получения уведомлений.

После того как у вас появится тема, в которую может публиковать сообщения учетная запись службы push-уведомлений Classroom API, вы можете зарегистрироваться для получения уведомлений, используя метод registrations.create() . Метод registrations.create() проверяет, доступна ли предоставленная тема Cloud Pub/Sub для учетной записи службы push-уведомлений. Метод завершится неудачей, если учетная запись службы push-уведомлений не сможет получить доступ к теме; например, если тема не существует или вы не предоставили ей разрешение на публикацию в этой теме.

Авторизация

Как и все вызовы API Classroom, вызовы registrations.create() должны быть авторизованы с помощью токена авторизации. Этот токен аутентификации должен включать область действия Push Notifications ( 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 .

Получать уведомления

Notifications are encoded with JSON, and contain:

  • Название коллекции, содержащей измененный ресурс. Для уведомлений об изменениях в списке студентов это может быть courses.students или courses.teachers . Для изменений в учебных заданиях это может быть courses.courseWork или courses.courseWork.studentSubmissions .
  • Идентификаторы ресурса, который изменился, в виде карты. Эта карта предназначена для сопоставления аргументов с методом 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 , содержащий идентификатор регистрации, вызвавшей уведомление, который можно использовать с registrations.delete() для отмены регистрации на получение уведомлений.