На этой странице представлена необходимая информация о создании и настройке проектов Google Cloud для надстроек Класса. Проекты Google Cloud используются для реализации системы единого входа Google через OAuth 2.0 (Google SSO), для авторизации запросов, сделанных вашим дополнением, а также для управления списком надстроек в магазине Google Workspace Marketplace.
Более общую информацию о публикации надстройки в Marketplace см. в разделе Публикация приложения .
Создание проекта Google Cloud
Существует два типа проектов: частный проект, используемый для разработки, и общедоступный проект, доступный конечным пользователям. Метки «общедоступный» и «частный» относятся к видимости вашего приложения в Google Workspace Marketplace ; частное приложение Marketplace может быть установлено только пользователями в том домене, в котором оно было создано, а общедоступное приложение Marketplace доступно для любого домена Google Workspace. Это должны быть два отдельных приложения, поскольку проект не может быть одновременно публичным и частным. Публичные приложения должны быть проверены и одобрены, прежде чем они станут доступны на рынке.
Для получения общей информации о создании проекта Google Cloud посетите раздел «Создание проекта Google Cloud» .
Создайте общедоступный проект Google Cloud.
Этот проект представляет собой дополнительное приложение, доступное администраторам, преподавателям и учащимся. Публичный проект должен быть рассмотрен и одобрен командой Google Workspace Marketplace, прежде чем его можно будет запустить или установить.
Создайте новый проект Google Cloud в своем рабочем домене.
Включите Classroom API в своем облачном проекте.
Включите SDK Google Workspace Marketplace в своем облачном проекте.
Установите для параметра «Видимость приложения конфигурации приложения Marketplace SDK» значение « Общедоступное» и установите флажок «Не в списке» .
Заполните обязательные поля на странице списка магазинов Marketplace SDK и нажмите «ОППУБЛИКОВАТЬ» .
Ваше приложение будет рассмотрено командой Google Workspace Marketplace. Они будут связываться с вами, используя адрес электронной почты разработчика, указанный в SDK Marketplace. После того как приложение будет одобрено, снимите флажок «Не в списке» , чтобы преподаватели и администраторы могли найти его в Marketplace .
Создайте частный проект Google Cloud.
Этот частный проект представляет собой дополнительное приложение, используемое для разработки. Он недоступен пользователям за пределами домена, в котором он был создан, но его не требуется утверждать перед установкой. Поэтому Google рекомендует использовать этот проект для разработки и тестирования вашего дополнения в контролируемой среде.
Для создания частного проекта вам потребуется доступ к домену Google Workspace for Education с лицензией Teaching & Learning или Plus. Если у вас еще нет доступа к такому домену, выполните следующие действия, чтобы настроить демонстрационный домен Google Workspace for Education, обновить его до лицензии Plus и предоставить ему доступ к API надстроек Класса:
- Выполните действия, чтобы получить тестовый домен для разработчиков .
Войдя в качестве администратора в демонстрационном домене, создайте новый проект Google Cloud.
Если вы не можете получить доступ к консоли Google Cloud или создать облачные проекты, проверьте следующее в консоли администратора :
- Перейдите на страницу «Настройки учетной записи» > «Настройки доступа по возрасту» и выберите параметр « Все пользователи в этой группе или организационном подразделении старше 18 лет» .
- В разделе «Приложения» > «Дополнительные службы Google» :
- Google Cloud Platform включена для всех .
- Настройки создания проектов: Разрешить пользователям создавать проекты .
- Настройки доступа к Cloud Shell: Разрешить доступ к Cloud Shell .
Заполните и отправьте форму запроса на обновление демонстрационного домена . Отправка этой формы требует от Google обновить ваш демонстрационный домен до Google Workspace for Education Plus с десятью лицензиями и разрешить вашему облачному проекту доступ к API надстроек Класса.
Вы получите электронное письмо, когда процессы обновления и создания белого списка будут завершены. Назначьте лицензии Plus своим учетным записям преподавателей-тестировщиков в консоли администратора . В разделе «Каталог» > «Пользователи» создайте или выберите учетные записи преподавателей-тестировщиков. В Лицензиях каждого преподавателя подтвердите, что Google Workspace for Education Plus назначен .
Включите Classroom API в своем облачном проекте.
Включите SDK Google Workspace Marketplace в своем облачном проекте.
Установите для параметра «Конфигурация приложения Marketplace SDK» значение «Видимость приложения» как частное .
Заполните обязательные поля на странице списка магазинов Marketplace SDK и нажмите «ОППУБЛИКОВАТЬ» . После публикации списка приложений пользователи домена смогут найти и установить приложение в Google Workspace Marketplace или посетив URL-адрес приложения , указанный на странице списка приложений в магазине.
ОАутентификация 2.0
Для доступа к API Класса требуется согласие пользователя на доступ к данным. Их можно получить , запросив у Google доступ к областям OAuth для вошедшего в систему пользователя и получив токен, который можно использовать для последующего выполнения вызовов API в Google Classroom. Области действия необходимо настроить в списке магазина Google Workspace Marketplace, чтобы администратор домена мог предоставить согласие от имени пользователей своего домена, если они установят надстройку.
Подробный список всех доступных областей действия и их использования см. на странице «Области OAuth для API Google» . См. страницу «Настройка OAuth» в документации Workspace для получения общей информации о конфигурации OAuth.
Разрешения пользователя
Ваше веб-приложение должно запрашивать хотя бы одну из следующих областей:
-
https://www.googleapis.com/auth/userinfo.email
, который позволяет приложению просматривать адрес электронной почты пользователя. -
https://www.googleapis.com/auth/userinfo.profile
, который позволяет приложению видеть личную информацию, такую как портрет, имя и фамилия, а также другую личную информацию, которую пользователь сделал общедоступной.
После того как пользователь авторизовал одну из этих областей в вашей надстройке, они идентифицируются параметром запроса login_hint
. Этот параметр передается любому URL-адресу вашего веб-приложения при открытии iframe. Если пользователь не авторизовал одну из этих областей, login_hint
не будет отправлен.
login_hint
— это стандартные параметры OpenID Connect, которые вы можете при необходимости передать в Google при использовании входа в Google или запросе токена OAuth. Он предназначен для упрощения процесса авторизации для конечного пользователя.
Область действия дополнений для Класса
Следующие области действия характерны для дополнений Класса:
-
https://www.googleapis.com/auth/classroom.addons.teacher
, который обеспечивает доступ ко всем методам API. -
https://www.googleapis.com/auth/classroom.addons.student
, который позволяет запускать операции проверки и чтения вложений.
Даже при наличии действующего токена доступа OAuth, обозначающего учетные данные пользователя, вызовы API ограничиваются дополнительными требованиями:
- Все методы требуют, чтобы пользователь был учителем или студентом курса, указанного в
courseId
в запросе. - Для создания, обновления, удаления и возврата оценок вложения требуется, чтобы пользователь был учителем.
- Вызовы к определенному сообщению Google Classroom контролируются следующими проверками.
- Если дополнение уже имеет хотя бы одно вложение к сообщению, оно может запрашивать:
- проверка запуска iframe
- Операции чтения, обновления и удаления вложений
- Обновления оценок за эту публикацию
- При первом открытии iframe обнаружения вложений надстройка может еще не иметь вложения к сообщению. Предоставляется параметр запроса
addOnToken
, который можно использовать для выполнения запросов на следующее:- Создание вложения под публикацией (необходим
addOnToken
) - Проверка запуска (
addOnToken
проверяется, если он предоставлен, и требуется, когда надстройка не имеет существующего вложения в сообщении)
- Создание вложения под публикацией (необходим
- Если дополнение уже имеет хотя бы одно вложение к сообщению, оно может запрашивать:
Проверка OAuth
Надстройка Класса использует API Google для доступа к данным пользователей Google.
Дополнительные сведения о процессе проверки см. в разделе часто задаваемых вопросов по проверке OAuth API .
Листинг Google Workspace Marketplace
Для получения общей информации о конфигурации SDK Google Workspace Marketplace посетите разделы «Включение и настройка SDK Google Workspace Marketplace» и «Создание листинга магазина Google Workspace Marketplace» .
Рекомендации по листингу
В списке магазинов Marketplace SDK вашего общедоступного проекта Google Cloud указаны имя и описания вашего приложения, предназначенные для конечных пользователей. Вы можете предоставить эти сведения на нескольких языках в разделе «Сведения о приложении» .
Соблюдайте следующие правила в своих объявлениях:
В разделе «Информация о приложении» :
Избегайте знаков препинания в названии приложения. Например, используйте « Моя надстройка от моей компании » вместо «Моя компания: Моя надстройка» или «Моя надстройка от моей компании».
Краткое описание и Подробное описание не должны содержать одинаковый текст.
+ Убедитесь, что вы выбрали значение для поля «Цена» . В этом поле представлены варианты « Бесплатно» , «Платно с бесплатной пробной версией », «Платно с бесплатными функциями » и «Платные цены». Вам не нужно указывать сумму стоимости в листинге на торговой площадке.
Убедитесь, что вы выбрали значение для поля «Категория» . Академические ресурсы или инструменты для учителей и администратора могут быть хорошим выбором в качестве дополнения к Классу.
Для получения дополнительной информации см. элементы, перечисленные в подробном описании приложения Marketplace.
В разделе «Графические ресурсы» :
Все предоставленные графические ресурсы не являются нечеткими и соответствуют размерам, указанным в стандартах Google Workspace Marketplace.
Все предоставленные снимки экрана являются точным представлением вашего опыта работы с дополнением .
В разделе «Ссылки на поддержку» :
- Убедитесь, что вы предоставили ссылку на Условия использования вашего приложения.
Убедитесь, что вы соблюдаете рекомендации Google API по брендингу , которые касаются разрешенных имен и описаний.
Если вы ссылаетесь на какой-либо продукт Google в своем списке, используйте его название в формате, указанном в Списке товарных знаков . Обязательно укажите символ товарного знака (™), если он указан; используйте « Google Docs™ », а не «Google Docs».
Интеграция со службами лицензирования и выставления счетов Google.
Если вы заинтересованы в интеграции ваших приложений Google Workspace Marketplace со службами лицензирования и выставления счетов Google, посетите Marketplace API .
Настройки установки
Надстройки могут обеспечивать индивидуальную установку в дополнение к установке администратором . На этой странице показаны некоторые различия между двумя типами установки. он не предназначен для продвижения любого типа установки. Вы можете выбрать, разрешить ли индивидуальную установку, на странице конфигурации приложения SDK Google Workspace Marketplace .
Установка администратора
Установки администратора позволяют администратору добавлять надстройку ко всем учетным записям в домене или к определенным группам доступа или организационным подразделениям. Только администратор домена может выполнить установку администратора. При необходимости администратор может дать согласие на все области доступа от имени всех пользователей в домене; пользователям не предлагается дать согласие на какие-либо области доступа, если администратор решит это сделать.
Ниже приведены некоторые соображения относительно установки администратором.
- Более жесткий контроль. Администраторы могут ограничить доступ пользователей к надстройке.
- Совместимость с лицензированием. Если вашему приложению требуется лицензия, передача установок через администратора может помочь обеспечить правильное распространение и использование лицензий в соответствующем учреждении.
- Снижение нагрузки на конечных пользователей. Установка администратором снижает нагрузку на преподавателей и учащихся по настройке. Это может привести к более удобному пользовательскому интерфейсу с меньшим количеством кликов и меньшим количеством возможностей для путаницы.
Дополнительные сведения о том, как выполнять установку с правами администратора, а также о том, как работает организационная структура, см. в разделе Установка приложений из Marketplace в вашем домене , чтобы узнать больше об организационных подразделениях и группах доступа.
Индивидуальная установка
Индивидуальные установки добавляют надстройку к собственной учетной записи пользователя. Во время установки пользователю будет предложено дать согласие на доступ к надстройке.
Ниже приведены некоторые соображения относительно индивидуальной установки.
- Содействие усыновлению. Больше пользователей смогут просмотреть и установить ваше дополнение из Google Workspace Marketplace. Разрешение индивидуальной установки может побудить больше учителей принять ваш продукт или поддержать его.
- Тестирование администратора. Администратор может индивидуально установить надстройку, чтобы протестировать или оценить ее, прежде чем утверждать или устанавливать ее для более широкой группы.
Помимо установки надстроек от имени пользователей, администраторы также могут вести белый список, позволяющий пользователям устанавливать надстройки, допускающие индивидуальную установку. Если надстройка отсутствует в белом списке, пользователи все равно смогут видеть ее список в Google Workspace Marketplace, но не смогут установить надстройку; вместо этого они видят сообщение, объясняющее, что администратор домена не разрешил установку надстройки. Чтобы узнать больше об этом поведении, ознакомьтесь с разделом «Управление приложениями Google Workspace Marketplace» в вашем белом списке .
Дополнительную информацию см. в документации по настройкам установки Google Workspace Marketplace.
Интеграция приложений
Вы должны указать URL-адрес запуска iframe в поле URI настройки вложения . Этот URL-адрес используется в качестве значения iframe src
для iframe обнаружения вложений . iframe обнаружения вложений используется учителями для поиска контента или действий, которые можно прикрепить к их заданию.
Вы также должны указать все префиксы URI , из которых разрешены вложения из вашего дополнения. Эта функция повышает безопасность, предотвращая вложения из неавторизованных источников.
Дополнительную информацию об этих полях см. на странице руководства по iframes .
Тестовые аккаунты
Создайте тестовые учетные записи на своем демонстрационном домене, чтобы проверить правильность поведения вашего частного дополнения. Для тестирования переключения между студентами в iframe «Просмотр работ учащихся» необходимы две учетные записи учащихся.
Рекомендуемые тестовые аккаунты:
- Тэмми Учитель, tammy.teacher@<ваш демо-домен>
- Сэм Студент, sam.student@<ваш демо-домен>
- Салли Студент, sally.student@<ваш демо-домен>
Выполните следующую процедуру, чтобы создать новую тестовую учетную запись :
- Войдите в консоль администратора .
- Перейдите к «Пользователи» .
- Нажмите «Добавить нового пользователя» (см. рис. 1).
- Введите информацию о пользователе и назначьте соответствующие роли.
Рисунок 1. Расположение ссылки «Добавить нового пользователя» в консоли администратора.
Выполните следующую процедуру, чтобы создать новую тестовую группу :
- Войдите в консоль администратора .
- Перейдите к Группам .
- Нажмите «Создать группу» (см. рис. 2).
- Введите участников и владельцев группы.
Рисунок 2. Расположение ссылки «Создать группу» в консоли администратора.