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 и включите выставление счетов для своего проекта Developer Console.

  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-уведомлений разрешение на публикацию в вашей теме Cloud Pub/Sub, пользователи, которые могут делать запросы из вашего проекта Developer Console, смогут определить, что она существует, и зарегистрироваться для получения уведомлений в ней. Многие приложения хранят идентификаторы клиентов OAuth на стороне клиента, поэтому конечные пользователи могут делать запросы из вашего проекта Developer Console. Если это относится к вам и вы обеспокоены тем, что конечные пользователи отправляют нежелательные уведомления в вашу тему Cloud Pub/Sub или знаете названия тем Cloud Pub/Sub, которые вы используете для push-уведомлений, вам следует рассмотреть возможность регистрации для получения push-уведомлений из другого проекта Developer Console.

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

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

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