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

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

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

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

Ключевой момент: Ваше производственное приложение надстройки должно иметь публичную видимость, установленную в Google Workspace Marketplace SDK. Частный проект может быть полезен для разработки и тестирования вашего дополнения, но требуется только публичный.

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

Важно: Вы не можете преобразовать частный проект в публичный.

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

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

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

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

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

   Важно: убедитесь, что проект принадлежит вашему производственному домену и что вы вошли в консоль Google Cloud как пользователь этого домена.
   Предупреждение: для тестирования необходимо использовать версию Draft вашего проекта. Для получения дополнительной информации см. раздел Обновление списка приложений с помощью черновиков .

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

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

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

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

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

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

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

6. Ваше приложение будет рассмотрено командой Google Workspace Marketplace. Они свяжутся с вами, используя адрес электронной почты разработчика, указанный в Marketplace SDK. После одобрения приложения снимите флажок Unlisted , чтобы преподаватели и администраторы могли найти его в 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, используя учетную запись администратора демонстрационного домена.

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

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

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

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

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

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

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

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

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

7. Заполните необходимые поля на странице Marketplace SDK Store Listing и нажмите PUBLISH . После публикации листинга приложения пользователи в домене могут найти и установить приложение в Google Workspace Marketplace или посетив URL-адрес приложения, показанный на странице Store Listing.

OAuth 2.0

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

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

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

Предупреждение: Если вы используете существующий проект Google Cloud для разработки надстройки, не запрашивайте новые области в коде для существующих продуктов до завершения проверки. Используйте отдельный поток авторизации, тестовую среду или установите флаг функции, чтобы запрашивать эти области только для маршрутов, связанных с надстройками, до завершения проверки.

Подробный список всех доступных областей и их использования см. на странице OAuth Scopes for Google APIs. Общую информацию о конфигурации OAuth см. на странице Configure OAuth в документации Workspace.

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

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

• https://www.googleapis.com/auth/userinfo.email , который позволяет приложению просматривать адрес электронной почты пользователя.
• https://www.googleapis.com/auth/userinfo.profile , который позволяет приложению видеть личную информацию, такую ​​как портрет, имя и фамилия, а также другую личную информацию, которую пользователь сделал общедоступной.

После того, как пользователь авторизовал одну из этих областей в вашем дополнении, они идентифицируются параметром запроса login_hint . Этот параметр передается в любой URL вашего веб-приложения при открытии iframe. Если пользователь не авторизовал одну из этих областей, login_hint не будет отправлен.

Предупреждение: Ваше приложение должно запросить по крайней мере одну из областей userinfo.email или userinfo.profile , чтобы получать 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

Примечание: Вы не можете создать демонстрационное видео для отправки в рамках процесса проверки OAuth. Вместо этого опубликуйте дополнение без проверки OAuth . Это оповестит команду проверки Google Workspace Marketplace о необходимости сделать демонстрационное видео от вашего имени. Затем группа проверки предоставит вам видео, чтобы вы могли включить его в отправку проверки OAuth.

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

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

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

Листинг Google Workspace Marketplace

Предупреждение: после сохранения параметра видимости во время процесса публикации вы не сможете изменить свой выбор позже.

Для получения общей информации о конфигурации Google Workspace Marketplace SDK посетите страницы Включение и настройка Google Workspace Marketplace SDK и Создание листинга магазина Google Workspace Marketplace .

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

В вашем публичном проекте Google Cloud Marketplace SDK Store Listing указывается имя и описание вашего приложения, предназначенные для конечных пользователей. Вы можете предоставить эти данные на нескольких языках в разделе App Details .

При составлении объявлений следуйте этим рекомендациям:

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

Важно: проверьте сведения о приложении для каждого языка, на котором вы предлагаете свое дополнение.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Тэмми Учитель, tammy.teacher@<ваш демо-домен>
• Сэм Студент, sam.student@<ваш демо-домен>
• Салли Студент, sally.student@<ваш демо-домен>

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

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

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

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

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

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