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

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

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

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

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

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

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

Для получения общей информации о создании проекта Google Cloud посетите раздел «Создание проекта Google Cloud» .

Создайте общедоступный проект Google Cloud.

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

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

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

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

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

   Включите API Класса

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

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

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

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

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

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

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

   Предупреждение. Убедитесь, что проект принадлежит демонстрационному домену и что вы вошли в консоль Google Cloud, используя учетную запись администратора демо-домена.

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

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

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

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

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

   Включите API Класса

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

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

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

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

ОАутентификация 2.0

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

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

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

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

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

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

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

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

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

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

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

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

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

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