Используют ли ваши пользователи Класс с Google Meet? Ознакомьтесь с кратким руководством по скрипту приложений, в котором рассказывается, как проверить посещаемость учащихся на курсах Google Meet .

Push-уведомления в Classroom API

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

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

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

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

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

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

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

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

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

Типы фидов

В настоящее время Classroom 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 в консоли разработчика (самый простой способ), с помощью инструмента командной строки (для простого программного использования) или с помощью Cloud Pub/Sub API . Обратите внимание, что 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-уведомлений не может получить доступ к теме; например, если тема не существует или вы не предоставили ей разрешение на публикацию в этой теме.

Авторизация

Как и все вызовы 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.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() . Точно так же изменения в коллекции курсов.courseWork будут иметь courseId и id , которые могут быть отправлены без изменений в курсы.courseWork.get() , а изменения в коллекции курсов.courseWork.studentSubmissions будут иметь courseId , courseWorkId и id , которые могут быть отправлено без изменений в курсы.courseWork.studentSubmissions.get() .

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

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

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