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

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

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

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

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

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

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

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

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

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

Типы фидов

API Класса в настоящее время предлагает три типа каналов:

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

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

Зарегистрируйте свое приложение для уведомлений

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

Авторизация

Как и все вызовы API класса, вызовы registrations.create() должны быть авторизованы с помощью токена авторизации. Этот токен аутентификации должен включать область действия push-уведомлений ( 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() . Аналогичным образом, изменения в коллекции CourseId и id будут иметь поля courseId и id , которые можно будет отправлять в неизмененном виде в CourseWork.get() , а изменения в коллекции courseId , courseWorkId и id , которые могут быть изменены. отправляется без изменений в CourseWork.studentSubmissions.get() .

В следующем фрагменте кода показан пример уведомления:

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

Уведомления также имеют атрибут сообщения registrationId , содержащий идентификатор регистрации, вызвавшей уведомление, который можно использовать с registrations.delete() для отмены регистрации в уведомлениях.