Прохождения

Эта серия пошаговых руководств иллюстрирует все движущиеся части работающего дополнения для Класса. Каждый шаг пошагового руководства рассматривает определенные концепции и реализует их в одном веб-приложении. Цель — помочь вам в установке, настройке и запуске функционального дополнения.

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

В этом руководстве рассматриваются следующие темы:

• Используйте Google Cloud, чтобы создать страницу для отображения в iframe в Классе.
• Добавьте систему единого входа Google (SSO) и разрешите пользователям входить в систему.
• Выполняйте вызовы API, чтобы прикрепить надстройку к заданию.
• Укажите ключевые требования к отправке дополнений и необходимые функции.

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

Пример реализации

Полный справочный пример доступен на Python . Частичные реализации также доступны в Java и Node.js. Эти реализации являются источниками примера кода, который можно найти на последующих страницах.

Где скачать

Примеры Python и Java доступны в репозиториях GitHub:

• репозиторий Python

• Java-репозиторий

Пример Node.js можно загрузить в виде zip-файла:

• Архив Node.js

Предварительные условия

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

HTTPS-сертификат

Хотя вы можете разместить свое приложение в любой среде разработки, надстройка для Класса доступна только через https:// . Поэтому вам понадобится сервер с SSL-шифрованием для развертывания вашего приложения или его тестирования в надстройке iframe.

Можно использовать localhost с сертификатом SSL; рассмотрите mkcert, если вам нужно создать сертификат для локальной разработки.

Проект Google Cloud

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

По завершении загрузите свой идентификатор клиента OAuth 2.0 в виде файла JSON; вам необходимо добавить этот файл учетных данных в распакованный каталог примера. См. раздел Понимание файлов для определенных расположений.

Учетные данные OAuth

Ключевой момент: ваше веб-приложение должно использовать учетные данные OAuth 2.0, управляемые в Google Cloud.

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

• Перейдите на страницу учетных данных Google Cloud . Убедитесь, что в верхней части экрана выбран правильный проект.
• Нажмите CREATE CREDENTIALS и выберите идентификатор клиента OAuth из раскрывающегося списка.
• На следующей странице:
  • Установите тип приложения на Веб-приложение .
  • В разделе «Разрешенные URI перенаправления» нажмите «ДОБАВИТЬ URI» . Добавьте полный путь для маршрута обратного вызова для вашего приложения. Например, https://my.domain.com/auth-callback или https://localhost:5000/callback . Этот маршрут вы создадите и обработаете позже в этом пошаговом руководстве. Вы можете изменить или добавить больше таких маршрутов в любое время.
  • Нажмите СОЗДАТЬ .
• Затем вы получите диалоговое окно с вашими вновь созданными учетными данными. Выберите опцию СКАЧАТЬ JSON . Скопируйте загруженный файл JSON в каталог вашего сервера.

Предварительные требования для конкретного языка

Просмотрите файл README в каждом репозитории, чтобы получить самый актуальный список необходимых условий.

Питон

В нашем примере на Python используется фреймворк Flask . Вы можете скачать полный исходный код по предоставленным ссылкам .

При необходимости установите Python 3.7+ и убедитесь, что pip доступен.

python3 -m ensurepip --upgrade

Мы также рекомендуем вам настроить и активировать новую виртуальную среду Python.

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

В каждом подкаталоге пошагового руководства в загруженных примерах есть файл requirements.txt . Вы можете быстро установить необходимые библиотеки с помощью pip . Используйте следующие команды для установки необходимых библиотек для первого прохождения.

cd flask/01-basic-app
pip install -r requirements.txt

Node.js

В нашем примере Node.js используется фреймворк Express . Вы можете скачать полный исходный код по предоставленным ссылкам .

Для этого примера требуется Node.js версии 16.13 или более поздней.

Установите необходимые модули узла с помощью npm .

npm install

Ява

В нашем примере на Java используется фреймворк Spring Boot . Вы можете скачать полный исходный код по предоставленным ссылкам .

Установите Java 11+, если она еще не установлена ​​на вашем компьютере.

Приложения Spring Boot могут использовать Gradle или Maven для обработки сборок и управления зависимостями. Этот пример включает оболочку Maven, которая обеспечивает успешную сборку без необходимости установки самого Maven.

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

java --version
./mvnw --version

Или в Windows:

java -version
mvnw.cmd --version

Разобраться с файлами

В следующих разделах описывается расположение примеров каталогов.

Имена каталогов

Каждый репозиторий содержит несколько каталогов, имена которых начинаются с цифры, например /01-basic-app/ . Цифры соответствуют конкретным шагам прохождения. Каждый каталог содержит полнофункциональное веб-приложение, реализующее функции, описанные в конкретном пошаговом руководстве. Например, каталог /01-basic-app/ содержит окончательную реализацию пошагового руководства по созданию надстройки .

Содержимое каталога

Содержимое каталога различается в зависимости от языка реализации:

Питон

• В корне каталога находятся следующие файлы:

  • main.py — точка входа приложения Python. Укажите в этом файле конфигурацию сервера, которую вы хотите использовать, а затем запустите ее, чтобы запустить сервер.
  • requirements.txt — модули Python, необходимые для запуска веб-приложения. Их можно установить автоматически с помощью pip install -r requirements.txt .

  • client_secret.json — секретный файл клиента, загруженный из Google Cloud. Обратите внимание, что это не включено в архив примеров; вам следует переименовать и скопировать загруженный файл учетных данных в корень каждого каталога.

    Важно! Прежде чем запускать примеры, вам необходимо предоставить секретный файл клиента из вашего проекта Google Cloud .

• config.py — параметры конфигурации сервера Flask.

• Каталог webapp содержит содержимое веб-приложения. Он включает в себя следующее:

• Каталог /templates/ с шаблонами Jinja для различных страниц.

• Каталог /static/ с изображениями, CSS и вспомогательными файлами JavaScript.

• routes.py — методы обработчика маршрутов веб-приложения.

• __init__.py — инициализатор модуля webapp . Этот инициализатор запускает сервер Flask и загружает параметры конфигурации, установленные в config.py .

• Дополнительные файлы, необходимые для конкретного шага пошагового руководства.

Node.js

Каждый шаг пошагового руководства можно найти в отдельной подпапке <step> . Каждый шаг содержит:

• Статические файлы, такие как JavaScript, CSS и изображения, находятся в папке ./<step>/public public.
• Маршрутизаторы Express находятся в папках ./<step>/routes routes.
• HTML-шаблоны находятся в папках ./<step>/views views.
• Серверное приложение — ./<step>/app.js .

Ява

Каталог проекта включает в себя следующее:

• Каталог src.main содержит исходный код и конфигурацию для успешного запуска приложения. Этот каталог включает в себя следующее: + Каталог java.com.addons.spring содержит файлы Application.java и Controller.java . Файл Application.java отвечает за работу сервера приложений, а файл Controller.java отвечает за логику конечной точки. + каталог resources содержит каталог templates с файлами HTML и JavaScript. Он также содержит файл application.properties , в котором указывается порт для запуска сервера, путь к файлу хранилища ключей и путь к каталогу templates . Этот пример включает файл хранилища ключей в каталоге resources . Вы можете сохранить его где угодно, но обязательно обновите файл application.properties , указав соответствующий путь.
  • pom.xml содержит информацию, необходимую для сборки проекта и определения необходимых зависимостей.
  • .gitignore содержит имена файлов, которые не следует загружать в git. Убедитесь, что вы добавили путь к своему хранилищу ключей в этом .gitignore . В приведенном примере это secrets/*.p12 (назначение хранилища ключей обсуждается в разделе ниже). В пошаговом руководстве 2 и последующих вам также следует указать путь к файлу client_secret.json , чтобы гарантировать, что вы не включите свои секреты в удаленный репозиторий. Для пошагового руководства 3 и последующих необходимо добавить путь к файлу базы данных H2 и фабрике хранилища файловых данных. Дополнительную информацию о настройке этих хранилищ данных можно найти в третьем пошаговом руководстве по обработке повторных посещений .
  • mvnw и mvnw.cmd — это исполняемые файлы-оболочки Maven для Unix и Windows соответственно. Например, запуск ./mvnw --version в Unix помимо прочей информации выводит версию Apache Maven.
  • Каталог .mvn содержит конфигурацию оболочки Maven.

Запустите образец сервера

Ключевой момент: ваше веб-приложение можно открыть в Google Classroom только через HTTPS. Дополнительные сведения см. в разделе сертификат HTTPS .

Вам необходимо запустить сервер, чтобы протестировать его. Следуйте этим инструкциям, чтобы запустить пример сервера на выбранном вами языке:

Питон

Учетные данные OAuth

Создайте и загрузите свои учетные данные OAuth, как описано ранее . Поместите файл JSON в корневой каталог рядом с файлом запуска сервера вашего приложения.

Настроить сервер

У вас есть несколько вариантов запуска веб-сервера. В конце вашего файла Python добавьте одно из следующего:

1. Незащищенный localhost . Обратите внимание, что это подходит только для непосредственного тестирования только в окне браузера; незащищенные домены невозможно загрузить в надстройку iframe для Класса.

   if __name__ == "__main__":
     # Disable OAuthlib's HTTPs verification.
     os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
   
     # Run the web app at http://localhost:5000.
     app.run(debug=True)
   

2. Безопасный localhost . Вы должны указать кортеж файлов ключей SSL для аргумента ssl_context .

   if __name__ == "__main__":
     # Run the web app at https://localhost:5000.
     app.run(host="localhost",
             ssl_context=("localhost.pem", "localhost-key.pem"),
             debug=True)
   

3. Сервер Гуникорн . Это подходит для готового к работе сервера или облачного развертывания. Мы рекомендуем установить переменную среды PORT для использования с этим вариантом запуска.

   if __name__ == "__main__":
     # Run the web app at https://<your domain>:<server_port>.
     # Defaults to https://<your domain>:8080.
     server_port = os.environ.get("PORT", "8080")
     app.run(debug=True, port=server_port, host="0.0.0.0")
   

Запустить сервер

Предупреждение. Перед запуском сервера вам необходимо настроить проект Google Cloud для доступа к API класса и необходимым учетным данным.

Запустите приложение Python, чтобы запустить сервер, настроенный на предыдущем шаге.

python main.py

Щелкните появившийся URL-адрес, чтобы просмотреть свое веб-приложение в браузере и убедиться, что оно работает правильно.

Node.js

Настроить сервер

Чтобы запустить сервер через HTTPS, вам необходимо создать самосертификат, который будет использоваться для запуска приложения через HTTPS. Эти учетные данные следует сохранить как sslcert/cert.pem и sslcert/key.pem в корневой папке репозитория. Возможно, вам придется добавить эти ключи в цепочку ключей вашей ОС, чтобы ваш браузер мог их принять.

Убедитесь, что *.pem находится в вашем файле .gitignore , поскольку вы не хотите фиксировать этот файл в git.

Запустить сервер

Предупреждение. Перед запуском сервера вам необходимо настроить проект Google Cloud для доступа к API класса и необходимым учетным данным.

Вы можете запустить приложение с помощью следующей команды, заменив step01 на правильный шаг, который вы хотите запустить в качестве сервера (например, step01 для 01-базовое приложение и step02 для 02-вход).

npm run step01

или

npm run step02

Это запустит веб-сервер по адресу https://localhost:5000 .

Вы можете завершить работу сервера с помощью Control + C в своем терминале.

Ява

Настроить сервер

Чтобы запустить сервер через HTTPS, вам необходимо создать самосертификат, который будет использоваться для запуска приложения через HTTPS.

Рассмотрите возможность использования mkcert для локальной разработки. После установки mkcert следующие команды генерируют локально хранимый сертификат для работы через HTTPS.

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

Этот пример включает файл хранилища ключей в каталоге ресурсов. Вы можете сохранить его где угодно, но обязательно обновите файл application.properties , указав соответствующий путь. Доменное имя — это домен, на котором вы запускаете проект (например, localhost ).

Убедитесь, что *.p12 находится в вашем файле .gitignore , поскольку вы не хотите фиксировать этот файл в git.

Запустить сервер

Предупреждение. Перед запуском сервера вам необходимо настроить проект Google Cloud для доступа к API класса и необходимым учетным данным.

Запустите сервер, запустив main метод в файле Application.java . Например, в IntelliJ вы можете либо щелкнуть правой кнопкой мыши Application.java > Run 'Application' в каталоге src/main/java/com/addons/spring , либо открыть файл Application.java и щелкнуть зеленую стрелку слева от подпись метода main(String[] args) . Альтернативно вы можете запустить проект в окне терминала:

./mvnw spring-boot:run

или в Windows:

mvnw.cmd spring-boot:run

Это запустит сервер по адресу https://localhost:5000 или по порту, указанному в application.properties .