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

Вы можете использовать методы из коллекции Registrations , чтобы получать уведомления об изменениях данных в Classroom.

В этой статье представлен концептуальный обзор, а также простые инструкции по началу получения push-уведомлений.

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

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

Для получения push-уведомлений необходимо настроить тему Cloud Pub/Sub и указать её имя при регистрации соответствующей ленты уведомлений.

Ниже приведены определения ключевых понятий, используемых в данной документации:

  • Пункт назначения — это место, куда отправляются уведомления.
  • Лента уведомлений — это тип уведомлений, на которые может подписаться стороннее приложение. Например, «изменения в списке студентов курса 1234».
  • Регистрация — это инструкция для API Classroom о доставке уведомлений из определенного канала в указанный пункт назначения .

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

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

Виды кормов

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

  • Для каждого домена существует лента изменений в списке участников , которая отображает уведомления о присоединении и выходе студентов и преподавателей из курсов в этом домене.
  • Для каждого курса предусмотрена функция отслеживания изменений в списке участников , которая отображает уведомления о присоединении и выходе студентов и преподавателей из данного курса.
  • Для каждого курса существует лента изменений учебных работ , которая отображает уведомления о создании или изменении любых объектов учебных работ или работ, сданных студентами, в рамках этого курса.

Настройте тему 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 поддерживает только ограниченное количество тем , поэтому использование одной темы для получения всех уведомлений гарантирует отсутствие проблем с масштабированием, если ваше приложение станет популярным.

  5. Создайте подписку в Cloud Pub/Sub , чтобы указать Cloud Pub/Sub, как доставлять ваши уведомления.

  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 .

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

Уведомления закодированы в формате JSON и содержат:

  • Название коллекции, содержащей измененный ресурс. Для уведомлений об изменениях в списке студентов это может быть 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() для отмены регистрации на получение уведомлений.