Учителя, использующие как Classroom, так и сторонние инструменты, сталкиваются с проблемой настройки своих курсов и списков на нескольких платформах. Это можно сделать вручную, используя загрузку CSV или вводя электронные письма по одному. Однако с помощью Classroom API сторонние инструменты могут снизить нагрузку на учителей за счет интеграции с наиболее распространенным вариантом использования API: импортом списка .
Импорт реестра позволяет сторонним платформам получать метаданные курса, преподавателей и студентов для каждого курса с разрешениями преподавателя или администратора . Преподаватели могут получать подробную информацию о курсах, которые они преподают, тогда как администраторы имеют доступ к сведениям обо всех курсах во всем домене . Такая гибкость позволяет разработчикам беспрепятственно добавлять списки учеников Класса на свою платформу как на уровне отдельного преподавателя, так и на уровне всего домена, используя учетные данные администратора.
Прежде чем углубляться в технические детали того, как может выглядеть интеграция импорта реестра, давайте сначала рассмотрим пример рабочего процесса:
В стороннем приложении преподаватель выбирает вариант импорта классного курса .
Стороннее приложение вызывает
courses.listчерез Classroom API, который вернет ответ в формате JSON со всеми курсами преподавателя.В ответе json стороннее приложение отображает названия курсов преподавателя, чтобы они могли выбрать один. Приложению необходимо будет отслеживать идентификаторы курсов, чтобы перейти к следующему шагу.
Используя выбранный идентификатор курса, стороннее приложение вызывает методы
students.listиteachers.listи отображает все имена на своем веб-сайте, чтобы учителя могли подтвердить импорт.Используя электронные письма, возвращенные в ответных json-файлах
students.listиteachers.list, стороннее приложение предлагает пользователям присоединиться к недавно импортированному курсу на их платформе.
Для каждого из методов, упомянутых в рабочем процессе, вы можете использовать API Explorer, чтобы точно увидеть, как ведет себя каждый метод. Прежде чем закончить это руководство, мы также рекомендуем прочитать следующее:
Начиная
Прежде чем приступить к реализации особенностей импорта списка участников Класса, вам необходимо определить, какую информацию о курсах и пользователях вам необходимо получить через API. Вы можете увидеть, какие метаданные курса доступны в справочной документации , но некоторые обязательные или общие поля можно кратко изложить ниже:
| Поле | Использовать |
|---|---|
| идентификатор | Требуется для запросов API, извлекающих учащихся или преподавателей. |
| имя | Рекомендуется для удобства использования пользователем, т.е. отображения на вашем сайте. |
| идентификатор владельца | Требуется при импорте по всему домену, чтобы правильно определить главного преподавателя курса. |
Информация о курсе извлекается на этапе courses.list описанного выше рабочего процесса. В этом запросе вы можете указать определенные параметры запроса. Хотя для этого метода ничего не требуется , некоторые рекомендуемые параметры:
| Параметр | Использовать |
|---|---|
| конечносостояние | Если не указать, API вернет курсы всех шести состояний курса . Мы рекомендуем указать ACTIVE , чтобы получить информацию о курсах, которые в настоящее время используют преподаватели. |
| размер страницы | Преподавателям, которые импортируют свои собственные курсы, мы рекомендуем указать небольшой (менее 10) размер страницы, чтобы уменьшить время ответа вызова API. |
| pageToken | Требуется, если вы используете постраничные запросы. |
| идентификатор учителя | Рекомендуется, поскольку администраторы домена часто проводят курсы. Если не указать, запрос вернет курсы для преподавателей во всем домене. |
| поля | Рекомендуется уменьшить время ответа вызова API. |
Используя идентификаторы курсов, полученные ранее, ваше приложение теперь может получить список студентов и преподавателей для этого курса или курсов. Этот идентификатор курса является единственным обязательным параметром запроса для teachers.list и students.list , но вы также можете рассмотреть возможность указания параметров pageSize и fields , чтобы уменьшить время ответа ваших вызовов API.
Все доступные поля для ресурсов учащихся и преподавателей можно найти в соответствующей документации. Два наиболее часто используемых и обычно обязательных поля находятся в поле profile : profile.name и profile.emailAddress .
| Поле | Использовать |
|---|---|
| профиль.имя | Рекомендуется для удобства использования пользователем, т.е. отображения на вашем сайте. |
| профиль.адрес электронной почты | Требуется для приложений, стремящихся однозначно идентифицировать учащихся. |
Чтобы получить и использовать любую из этих сведений о курсе или списке из Класса, вашему приложению потребуется запросить авторизацию у пользователей. Для реализации этого рабочего процесса требуется три (3) области:
- https://www.googleapis.com/auth/classroom.courses.readonly
- Предоставляет доступ только для чтения к курсам Google Classroom.
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Предоставляет доступ только для чтения к спискам курсов Google Classroom (преподаватели и учащиеся).
- https://www.googleapis.com/auth/classroom.profile.emails
- Предоставляет доступ для чтения к электронной почте преподавателей и учащихся.
Синхронизировать списки с уведомлениями Pub/Sub
По ходу учебного года списки могут меняться по мере того, как учащиеся отказываются от курсов или добавляют их. Добавление уведомлений Pub/Sub позволит вам синхронизировать стороннее приложение с списками участников Класса. Чтобы получать уведомления, вы настраиваете тему Google Cloud Pub/Sub, а затем регистрируете ее с помощью Classroom API. Эта регистрация представляет собой запрос Классу на отправку данных из данного канала в данную тему. Этот канал будет триггером событий для повторной синхронизации со списком учителей в Классе.
Для использования push-уведомлений потребуется еще одна область действия, которую не нужно отправлять на проверку:
- https://www.googleapis.com/auth/classroom.push-notifications
- Позволяет вашему приложению регистрироваться для любых действий с push-уведомлениями.
Дополнительные сведения об интеграции с push-уведомлениями Класса см. в нашем руководстве по управлению push-уведомлениями .