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