Конфигурация проекта 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. Включите API Classroom в своем облачном проекте.

   Включите API для учебных классов

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

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

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

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

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

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

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

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

   Включите API для учебных классов

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

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

6. Установите параметр «Видимость приложения» в настройках приложения Marketplace SDK в значение «частный» .

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

OAuth 2.0

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

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

Подробный список всех доступных областей действия 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 .

Для получения дополнительной информации о процессе проверки обратитесь к разделу часто задаваемых вопросов (FAQ) по проверке API OAuth .

Список рабочих пространств Google на торговой площадке Google

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

Вопросы, касающиеся размещения объявления

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В поле «URI настройки вложений» необходимо указать URL-адрес запускаемого iframe. Этот 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. Расположение ссылки «Создать группу» в консоли администратора.