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

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

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

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

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

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

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

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

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

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

Типы кормов

API Classroom предлагает три типа каналов:

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

Примечание: Нам известно о проблеме, из-за которой не отправляются уведомления об изменениях в курсах, владелец которых не является участником домена Google Workspace for Education. Если вы работаете с курсами, не привязанными к домену Google Workspace for Education, имейте в виду, что уведомления для feedType COURSE_ROSTER_CHANGES могут не работать.

Настройте тему 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-уведомлений ( [e-mail] ) разрешение на публикацию в вашей теме.

Примечание: Если вы предоставите учётной записи службы Push-уведомлений разрешение на публикацию в вашей теме Cloud Pub/Sub, пользователи, которые могут отправлять запросы из вашего проекта консоли разработчика, смогут определить её существование и зарегистрироваться для получения уведомлений. Многие приложения хранят идентификаторы клиентов OAuth на стороне клиента, поэтому конечные пользователи могут отправлять запросы из вашего проекта консоли разработчика. Если это относится к вам, и вы обеспокоены тем, что конечные пользователи отправляют нежелательные уведомления в вашу тему Cloud Pub/Sub, или знаете названия тем Cloud Pub/Sub, которые вы используете для push-уведомлений, вам следует рассмотреть возможность регистрации для получения push-уведомлений из другого проекта консоли разработчика.

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

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

Авторизация

Как и все вызовы Classroom 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() . Аналогично, изменения в коллекции 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() для отмены регистрации в уведомлениях.