Конфигурация проекта Google Cloud

На этой странице представлена необходимая информация о создании и настройке проектов Google Cloud для надстроек Classroom. Проекты Google Cloud используются для реализации системы единого входа Google через OAuth 2.0 (Google SSO), авторизации запросов, выполняемых вашим дополнением, и управления размещением дополнений в магазине Google Workspace Marketplace.

Более общую информацию о публикации дополнения в Marketplace см. в разделе Публикация приложения .

Создание проекта Google Cloud

Существует два типа проектов: частный проект, предназначенный для разработки, и публичный проект, доступный конечным пользователям. Метки «публичный» и «частный» относятся к видимости вашего приложения в Google Workspace Marketplace ; частное приложение из Marketplace может быть установлено только пользователями в домене, в котором оно было создано, в то время как публичное приложение из Marketplace доступно в любом домене Google Workspace. Это должны быть два отдельных приложения, поскольку проект не может быть одновременно публичным и частным. Публичные приложения должны быть рассмотрены и одобрены перед размещением в Marketplace.

Общую информацию о создании проекта Google Cloud можно найти на странице Создание проекта Google Cloud .

Создайте публичный проект Google Cloud

Этот проект представляет собой дополнительное приложение, доступное администраторам, преподавателям и учащимся. Публичный проект должен быть рассмотрен и одобрен командой Google Workspace Marketplace перед запуском или установкой.

1. Создайте новый проект Google Cloud в вашем производственном домене.

   Создайте проект Google Cloud

2. Включите Classroom API в вашем облачном проекте.

   Включить API класса

3. Включите Google Workspace Marketplace SDK в своем облачном проекте.

   Включить Google Workspace Marketplace SDK

4. Установите для параметра Видимость приложения конфигурации приложения SDK Marketplace значение Публичное и отметьте галочкой поле Не в списке .

5. Заполните обязательные поля на странице описания магазина Marketplace SDK и нажмите кнопку ОПУБЛИКОВАТЬ .

6. Ваше приложение будет рассмотрено командой Google Workspace Marketplace. Они свяжутся с вами по адресу электронной почты разработчика, указанному в Marketplace SDK. После одобрения приложения снимите флажок «Не в списке» , чтобы преподаватели и администраторы могли найти его в Marketplace .

Создайте частный проект Google Cloud

Этот частный проект представляет собой приложение-надстройку, используемое для разработки. Оно недоступно пользователям за пределами домена, в котором оно было создано, но не требует одобрения перед установкой. Поэтому Google рекомендует использовать этот проект для разработки и тестирования вашего дополнения в контролируемой среде.

Для создания частного проекта вам потребуется доступ к домену Google Workspace for Education с лицензией Teaching & Learning или Plus. Если у вас ещё нет доступа к такому домену, выполните следующие действия, чтобы настроить демонстрационный домен Google Workspace for Education, обновить его до лицензии Plus и разрешить ему доступ к API надстроек Classroom:

1. Выполните следующие действия, чтобы получить тестовый домен для разработчиков .

2. Войдя в систему как администратор в демонстрационном домене, создайте новый проект Google Cloud.

   Создайте проект Google Cloud

   Если вы не можете получить доступ к консоли Google Cloud или создать облачные проекты, проверьте следующее в консоли администратора :

   • Перейдите на страницу Настройки учетной записи > Настройки доступа на основе возраста и выберите параметр Все пользователи в этой группе или организационном подразделении достигли возраста 18 лет .
   • В разделе Приложения > Дополнительные службы Google :
   • Облачная платформа Google доступна всем .
   • Настройки создания проектов: Разрешить пользователям создавать проекты .
   • Параметры доступа к Cloud Shell: Разрешить доступ к Cloud Shell .

3. Заполните и отправьте форму запроса на обновление демо-домена . Отправка этой формы требует от Google обновления вашего демо-домена до Google Workspace for Education Plus с десятью лицензиями и позволяет вашему облачному проекту использовать API дополнений Classroom.

   Вы получите электронное письмо после завершения обновления и добавления в разрешённый список. Назначьте лицензии Plus вашим учётным записям преподавателей-тестировщиков в консоли администратора . В разделе «Каталог» > «Пользователи» создайте или выберите учётные записи преподавателей-тестировщиков. В разделе «Лицензии» каждого преподавателя убедитесь, что лицензия Google Workspace for Education Plus назначена .

4. Включите Classroom API в вашем облачном проекте.

   Включить API класса

5. Включите Google Workspace Marketplace SDK в своем облачном проекте.

   Включить Google Workspace Marketplace SDK

6. Установите для параметра Видимость приложения конфигурации приложения SDK Marketplace значение « Частное» .

7. Заполните обязательные поля на странице описания приложения в Marketplace SDK и нажмите кнопку «ОПУБЛИКОВАТЬ» . После публикации приложения пользователи домена смогут найти и установить его в Google Workspace Marketplace или перейдя по URL-адресу приложения, указанному на странице описания приложения в Store.

OAuth 2.0

Для доступа к API Класса требуется согласие пользователя на доступ к данным. Для этого необходимо запросить у Google доступ к областям действия OAuth для вошедшего в систему пользователя и получить токен, который можно использовать для последующих вызовов API к Google Классу. Области действия необходимо настроить в описании магазина Google Workspace Marketplace, чтобы администратор домена мог предоставить согласие от имени пользователей домена при установке ими дополнения.

Поскольку области действия Classroom являются конфиденциальными, перед запуском дополнения необходимо запросить проверку OAuth. В противном случае пользователи увидят предупреждение о том, что приложение не проверено, и лишь ограниченное число пользователей смогут получить доступ к вашему продукту. Подробнее о проверке см. в обзоре последовательности проверки.

Подробный список всех доступных областей действия и их применения см. на странице «Области действия OAuth для API Google». Общую информацию о настройке OAuth см. на странице «Настройка OAuth» в документации Workspace.

Разрешения пользователя

Ваше веб-приложение должно запрашивать как минимум одну из следующих областей:

• 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. Он предназначен для упрощения процесса авторизации для конечного пользователя.

Области применения надстроек для занятий в классе

Следующие области действия относятся только к надстройкам Classroom:

• 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

Надстройка Classroom использует API Google для доступа к данным пользователей Google.

• Подтвердите идентичность вашего бренда .
• Проверьте конфиденциальные области OAuth .

Дополнительную информацию о процессе проверки см. в разделе часто задаваемых вопросов по проверке API OAuth .

Листинг Google Workspace Marketplace

Общую информацию о конфигурации Google Workspace Marketplace SDK можно найти в разделах Включение и настройка Google Workspace Marketplace SDK и Создание листинга магазина Google Workspace Marketplace .

Соображения относительно листинга

В описании вашего публичного проекта Google Cloud в Marketplace SDK указаны название и описание вашего приложения, предназначенные для конечных пользователей. Вы можете предоставить эту информацию на нескольких языках в разделе «Сведения о приложении» .

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

• В разделе «Сведения о приложении» :
  • Избегайте использования знаков препинания в названии приложения. Например, используйте « Моё дополнение от моей компании » вместо «Моя компания: Моё дополнение» или «Моё дополнение от моей компании».
  • Краткое описание и подробное описание не должны содержать один и тот же текст.
  • Убедитесь, что вы выбрали значение в поле «Цена» . Это поле включает в себя варианты «Бесплатно» , «Платно с бесплатным пробным периодом» , «Платно с бесплатными функциями » и «Платная цена». Указывать стоимость в описании на Marketplace не нужно.
  • Убедитесь, что вы выбрали значение в поле «Категория» . Для надстройки «Класс» хорошими вариантами могут быть «Академические ресурсы» или «Инструменты для учителя и администратора» .
  • Дополнительную информацию см. в описании приложений Marketplace.

• В разделе «Графические активы» :
  • Все предоставленные графические ресурсы не являются размытыми и соответствуют размерам, указанным в стандартах Google Workspace Marketplace.
  • Все предоставленные скриншоты являются точным отображением вашего опыта использования дополнения .
• В разделе «Ссылки поддержки» :
  • Убедитесь, что вы предоставили ссылку на Условия обслуживания вашего приложения.
• Убедитесь, что вы соответствуете правилам брендинга API Google , которые охватывают допустимые имена и описания.
• Если вы ссылаетесь на какой-либо продукт Google в своей публикации, используйте его название в формате, указанном в Списке товарных знаков . Обязательно укажите символ товарного знака (™), если он указан; используйте « Google Docs™ », а не «Google Docs».

Интеграция со службами лицензирования и выставления счетов Google

Если вы заинтересованы в интеграции своих приложений Google Workspace Marketplace со службами лицензирования и выставления счетов Google, посетите API Marketplace .

Настройки установки

Дополнения могут быть разрешены как для индивидуальной установки, так и для установки администратором . На этой странице описаны некоторые различия между двумя типами установки. Она не предназначена для продвижения какого-либо из них. Вы можете выбрать, разрешать ли индивидуальную установку, на странице конфигурации приложения SDK Google Workspace Marketplace .

Установка администратора

Административная установка позволяет администратору добавлять надстройку ко всем учётным записям в домене, к определённым группам доступа или организационным подразделениям. Административную установку может выполнять только администратор домена. При желании администратор может дать согласие на все области доступа от имени всех пользователей домена; пользователям не требуется давать согласие на какие-либо области доступа, если администратор этого захочет.

Ниже приведены некоторые соображения относительно установки администратора.

• Более строгий контроль. Администраторы могут ограничить доступ пользователей к дополнению.
• Совместимость с лицензированием. Если для вашего приложения требуется лицензия, передача установок через администратора может помочь гарантировать, что лицензии будут распределены и использованы надлежащим образом в соответствующем учреждении.
• Снижение нагрузки на конечных пользователей. Установка администратором снижает нагрузку на преподавателей и учащихся по настройке. Это может обеспечить более удобный пользовательский интерфейс с меньшим количеством щелчков мыши и меньшим количеством возможных путаниц.

Дополнительную информацию о выполнении административных установок см. в разделе Установка приложений Marketplace в вашем домене , а дополнительную информацию об организационных подразделениях и группах доступа см. в разделе Как работает организационная структура .

Индивидуальная установка

Индивидуальные установки добавляют дополнение к учётной записи пользователя. Во время установки пользователю предлагается согласиться с областями доступа, заданными дополнением.

Ниже приведены некоторые соображения относительно индивидуальной установки.

• Упростите внедрение. Больше пользователей смогут увидеть и установить ваше дополнение из Google Workspace Marketplace. Разрешение на индивидуальную установку может побудить больше учителей внедрить или поддержать ваш продукт.
• Тестирование администратором. Администратор может установить дополнение индивидуально, чтобы протестировать или оценить его, прежде чем одобрить или установить его для более широкой группы.

Помимо установки дополнений от имени пользователей, администраторы также могут вести разрешённый список, чтобы разрешить пользователям устанавливать дополнения, допускающие индивидуальную установку. Если дополнение отсутствует в разрешённом списке, пользователи всё равно смогут видеть его в Google Workspace Marketplace, но не смогут установить его; вместо этого они увидят сообщение о том, что администратор домена не разрешил установку дополнения. Подробнее об этом поведении см. в статье Управление приложениями Google Workspace Marketplace в разрешённом списке .

Дополнительную информацию см. в документации по параметрам установки Google Workspace Marketplace.

Интеграция приложений

Необходимо указать URL-адрес для запуска iframe в поле «URI настройки вложения» . Этот URL-адрес используется в качестве значения src для iframe «Обнаружение вложения» . iframe «Обнаружение вложения» используется преподавателями для поиска контента или заданий, которые можно прикрепить к заданию. Его можно настроить в консоли проекта Google Cloud.

Префиксы разрешенных URI вложений используются для проверки URI, заданных в AddOnAttachment , с помощью методов *.addOnAttachments.create и *.addOnAttachments.patch . Проверка осуществляется путем сопоставления префиксов строк и не допускает использования подстановочных знаков.

Вам также необходимо указать все префиксы URI , с которых разрешены вложения из вашего дополнения. Эта функция повышает безопасность, предотвращая вложения из неавторизованных источников.

Задайте оба этих значения на странице конфигурации приложения Marketplace SDK вашего проекта Google Cloud.

Тестовые аккаунты

Создайте тестовые учётные записи на вашем демонстрационном домене, чтобы проверить корректность работы вашего личного дополнения. Для тестирования переключения между учащимися в iframe для проверки студенческих работ необходимы две учётные записи.

Предлагаемые тестовые аккаунты:

• Тэмми Тичер, tammy.teacher@<ваш демонстрационный домен>
• Сэм Студент, sam.student@<ваш демонстрационный домен>
• Салли Студент, sally.student@<ваш демонстрационный домен>

Чтобы создать новую тестовую учетную запись , выполните следующие действия:

1. Войдите в консоль администратора .
2. Перейдите в раздел Пользователи .
3. Нажмите Добавить нового пользователя (см. рисунок 1).
4. Введите информацию о пользователе и назначьте соответствующие роли.

Рисунок 1. Расположение ссылки «Добавить нового пользователя » в консоли администратора.

Чтобы создать новую тестовую группу , выполните следующую процедуру:

1. Войдите в консоль администратора .
2. Перейдите в раздел Группы .
3. Нажмите Создать группу (см. рисунок 2).
4. Введите участников и владельцев группы.

Рисунок 2. Расположение ссылки «Создать группу» в консоли администратора.