Создать дополнение для Класса

Это первое пошаговое руководство из серии пошаговых руководств по дополнениям к Classroom.

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

В ходе этого пошагового руководства вы выполните следующее:

• Создайте новый проект Google Cloud для вашего дополнения.
• Создайте каркас веб-приложения с кнопками-заглушками для входа.
• Опубликуйте листинг вашего дополнения в магазине Google Workspace Marketplace.

После завершения вы можете установить свое дополнение и загрузить его в iframe дополнений для класса.

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

Предпосылки

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

Питон

В нашем примере Python используется фреймворк Flask . Вы можете загрузить полный исходный код для всех пошаговых инструкций со страницы обзора. Код для этого конкретного пошагового руководства можно найти в каталоге /flask/01-basic-app/ .

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

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

При необходимости установите NodeJS v16.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

Настройте проект Google Cloud

Доступ к API Classroom и требуемые методы аутентификации контролируются проектами Google Cloud. Следующие инструкции проведут вас через минимальные шаги по созданию и настройке нового проекта для использования с вашим дополнением.

Создать проект

Создайте новый проект Google Cloud, посетив страницу создания проекта . Вы можете указать любое имя для нового проекта. Нажмите Создать .

Для полного создания нового проекта потребуется несколько минут. После этого обязательно выберите проект ; вы можете выбрать его в раскрывающемся меню селектора проектов в верхней части экрана или нажать ВЫБРАТЬ ПРОЕКТ в меню уведомлений в правом верхнем углу.

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

Подключите Google Workspace Marketplace SDK к проекту Google Cloud

Перейдите в браузер API Library . Найдите Google Workspace Marketplace SDK . Вы должны увидеть SDK в списке результатов.

Выберите карточку Google Workspace Marketplace SDK, затем нажмите Включить .

Настройте Google Workspace Marketplace SDK

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

Конфигурация приложения

Перейдите на страницу конфигурации приложения Marketplace SDK. Укажите следующую информацию:

• Установите видимость приложения : Public или Private .

  • Публичный параметр предназначен для приложений, которые в конечном итоге будут выпущены для конечных пользователей. Публичное приложение должно пройти процесс утверждения, прежде чем оно будет опубликовано для конечных пользователей, но вы можете указать пользователей, которые могут установить и протестировать его как черновик . Это состояние перед публикацией, которое позволит вам протестировать и разработать свое дополнение перед отправкой его на утверждение.
  • Частная настройка подходит для внутреннего тестирования и разработки. Частное приложение могут установить только пользователи в том же домене, где был создан проект. Поэтому следует устанавливать видимость как частную, только если проект был создан в домене с подпиской Google Workspace for Education , иначе ваши тестовые пользователи не смогут запускать дополнения Classroom.
  Предупреждение: Проверьте правильность настройки видимости приложения перед сохранением. Вы не сможете изменить видимость приложения после ее настройки. Вам необходимо создать новый проект Google Cloud, чтобы задать другую видимость приложения.

• Если вы хотите разрешить установку Admin Only install администраторам домена, выберите в параметрах установки значение «Установить только администратора».

• В разделе Интеграция приложений выберите Дополнение класса . Вам будет предложено ввести защищенный URI настройки вложения; это URL, который вы ожидаете загрузить, когда пользователь открывает ваше дополнение. Для целей этого пошагового руководства это должно быть https://<your domain>/addon-discovery .

• Разрешенные префиксы URI вложений используются для проверки URI, установленных в AddOnAttachment , с помощью courses.*.addOnAttachments.create и courses.*.addOnAttachments.patch . Проверка представляет собой буквальное соответствие префикса строки и в настоящее время не позволяет использовать подстановочные знаки. Добавьте по крайней мере корневой домен вашего сервера контента, например https://localhost:5000/ или https://cdn.myedtech.com/ .

• Добавьте те же области OAuth , которые были указаны на экране согласия OAuth на предыдущем шаге.

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

• Заполните поля, соответствующие вашей организации, в разделе «Ссылки для разработчиков» .

Список магазинов

Перейдите на страницу Store Listing Marketplace SDK. Предоставьте следующую информацию:

• В разделе App Details добавьте язык или разверните раскрывающийся список рядом с уже указанным языком. Укажите имя приложения и описания; они появятся на странице листинга магазина Google Workspace Marketplace вашего дополнения. Нажмите Done , чтобы сохранить.
• Выберите категорию для вашего дополнения.
• В разделе Графические активы укажите изображения для требуемых полей. Их можно будет изменить позже, а пока они могут быть заполнителями.
• В разделе Support Links укажите запрошенные URL-адреса. Они могут быть заполнителями, если вы установили App Visibility на Private на предыдущем шаге.

Если вы установили App Visibility на Private на предыдущем шаге, нажмите PUBLISH ; ваше приложение сразу же будет доступно для установки. Если вы установили App Visibility на Public , добавьте адреса электронной почты в область Draft Testers для всех тестовых пользователей и нажмите Save Draft .

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

Экран согласия OAuth

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

Перейдите на страницу создания экрана согласия OAuth . Укажите следующую информацию:

• Установите Тип пользователя на Внешний . Нажмите Создать .
• На следующей странице заполните необходимые данные приложения и контактную информацию. Укажите любые домены, на которых размещено ваше приложение, в разделе Авторизованные домены . Нажмите СОХРАНИТЬ И ПРОДОЛЖИТЬ .

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

  Вы должны запросить по крайней мере одну из следующих областей, чтобы Google отправил параметр запроса login_hint . Более подробное объяснение этого поведения доступно в нашем руководстве по настройке OAuth :

  • https://www.googleapis.com/auth/userinfo.email (уже включено)
  • https://www.googleapis.com/auth/userinfo.profile (уже включено)

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

  • https://www.googleapis.com/auth/classroom.addons.teacher
  • https://www.googleapis.com/auth/classroom.addons.student

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

  Нажмите СОХРАНИТЬ И ПРОДОЛЖИТЬ .

• Перечислите адреса электронной почты всех тестовых аккаунтов на странице Тестовые пользователи . Нажмите СОХРАНИТЬ И ПРОДОЛЖИТЬ .

Подтвердите правильность настроек, затем вернитесь на панель управления.

Установить дополнение

Теперь вы можете установить свое дополнение, используя ссылку в верхней части страницы Store Listing Marketplace SDK. Нажмите View In Marketplace в верхней части страницы, чтобы увидеть список, затем выберите Install .

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

Создайте простое веб-приложение

Настройте скелет веб-приложения с двумя маршрутами. Дальнейшие шаги пошагового руководства расширят это приложение, поэтому сейчас просто создайте целевую страницу для надстройки /addon-discovery и фиктивную страницу индекса / для нашего "сайта компании".

Реализуйте эти две конечные точки:

• / : отображает приветственное сообщение и кнопку для закрытия как текущей вкладки, так и дополнительного iframe.
• /addon-discovery : отображает приветственное сообщение и две кнопки: одну для закрытия iframe надстройки и одну для открытия веб-сайта в новой вкладке.

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

Создать скрипт утилиты

Создайте каталог static/scripts . Создайте новый файл addon-utils.js . Добавьте следующие две функции.

/**
 *   Opens a given destination route in a new window. This function uses
 *   window.open() so as to force window.opener to retain a reference to the
 *   iframe from which it was called.
 *   @param {string} destinationURL The endpoint to open, or "/" if none is
 *   provided.
 */
function openWebsiteInNewTab(destinationURL = '/') {
  window.open(destinationURL, '_blank');
}

/**
 *   Close the iframe by calling postMessage() in the host Classroom page. This
 *   function can be called directly when in a Classroom add-on iframe.
 *
 *   Alternatively, it can be used to close an add-on iframe in another window.
 *   For example, if an add-on iframe in Window 1 opens a link in a new Window 2
 *   using the openWebsiteInNewTab function, you can call
 *   window.opener.closeAddonIframe() from Window 2 to close the iframe in Window
 *   1.
 */
function closeAddonIframe() {
  window.parent.postMessage({
    type: 'Classroom',
    action: 'closeIframe',
  }, '*');
};

Создать маршруты

Реализуйте /addon-discovery и / endpoints.

Питон

Настройте каталог приложений

Для целей этого примера структурируйте логику приложения как модуль Python. Это каталог webapp в нашем примере.

Создайте каталог для модуля сервера, например, webapp . Переместите static каталог в каталог модуля. Создайте каталог template в каталоге модуля; ваши файлы HTML будут здесь.

Построить серверный модуль *

Создайте файл __init__.py в каталоге вашего модуля и добавьте следующие импорты и объявления.

from flask import Flask
import config

app = Flask(__name__)
app.config.from_object(config.Config)

# Load other module script files. This import statement refers to the
# 'routes.py' file described below.
from webapp import routes

Затем создайте файл для обработки маршрутов веб-приложения. В нашем примере это webapp/routes.py . Реализуйте два маршрута в этом файле.

from webapp import app
import flask

@app.route("/")
def index():
    return flask.render_template("index.html",
                                message="You've reached the index page.")

@app.route("/classroom-addon")
def classroom_addon():
    return flask.render_template(
        "addon-discovery.html",
        message="You've reached the addon discovery page.")

Обратите внимание, что оба наших маршрута передают переменную message в соответствующие шаблоны Jinja. Это полезно для определения того, на какую страницу перешел пользователь.

Создание файлов конфигурации и запуска

В корневом каталоге вашего приложения создайте файлы main.py и config.py . Настройте свой секретный ключ в config.py .

import os

class Config(object):
    # Note: A secret key is included in the sample so that it works.
    # If you use this code in your application, replace this with a truly secret
    # key. See https://flask.palletsprojects.com/quickstart/#sessions.
    SECRET_KEY = os.environ.get(
        'SECRET_KEY') or "REPLACE ME - this value is here as a placeholder."

В файле main.py импортируйте свой модуль и запустите сервер Flask.

from webapp import app

if __name__ == "__main__":
    # Run the application over HTTPs with a locally stored certificate and key.
    # Defaults to https://localhost:5000.
    app.run(
        host="localhost",
        ssl_context=("localhost.pem", "localhost-key.pem"),
        debug=True)

Node.js

Маршруты регистрируются в файле app.js с помощью следующих строк.

const websiteRouter = require('./routes/index');
const addonRouter = require('./routes/classroom-addon');

app.use('/', websiteRouter);
app.use('/addon-discovery', addonRouter);

Откройте /01-basic-app/routes/index.js и просмотрите код. Этот маршрут достигается, когда конечный пользователь посещает веб-сайт компании. Маршрут отображает ответ с использованием шаблона index Handlebars и передает шаблону объект данных, содержащий переменные title и message .

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Education Technology',
    message: 'Welcome to our website!'
  });
});

Откройте второй маршрут /01-basic-app/routes/classroom-addon.js и просмотрите код. Этот маршрут достигается, когда конечный пользователь посещает дополнение. Обратите внимание, что этот маршрут использует шаблон discovery Handlebars и дополнительно макет addon.hbs для отображения страницы иначе, чем на веб-сайте компании.

router.get('/', function (req, res, next) {
  res.render('discovery', {
    layout: 'addon.hbs',
    title: 'Education Technology Classroom add-on',
    message: `Welcome.`
  });
});

Ява

В примере кода Java используются модули для упаковки последовательных шагов пошагового руководства. Поскольку это первое пошаговое руководство, код находится в модуле step_01_basic_app . не ожидается, что вы реализуете свой проект с помощью модулей; вместо этого мы предлагаем вам строить на основе одного проекта, следуя каждому шагу пошагового руководства.

Создайте класс контроллера, Controller.java в этом примере проекта, чтобы определить конечные точки. В этом файле импортируйте аннотацию @GetMapping из зависимости spring-boot-starter-web .

import org.springframework.web.bind.annotation.GetMapping;

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

@org.springframework.stereotype.Controller
public class Controller {

Затем реализуйте два маршрута и дополнительный маршрут для обработки ошибок.

/** Returns the index page that will be displayed when the add-on opens in a
*   new tab.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the index page template if successful, or the onError method to
*   handle and display the error message.
*/
@GetMapping(value = {"/"})
public String index(Model model) {
  try {
    return "index";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Returns the add-on discovery page that will be displayed when the iframe
*   is first opened in Classroom.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the addon-discovery page.
*/
@GetMapping(value = {"/addon-discovery"})
public String addon_discovery(Model model) {
  try {
    return "addon-discovery";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Handles application errors.
*   @param errorMessage message to be displayed on the error page.
*   @param model the Model interface to pass error information to display on
*   the error page.
*   @return the error page.
*/
@GetMapping(value = {"/error"})
public String onError(String errorMessage, Model model) {
  model.addAttribute("error", errorMessage);
  return "error";
}

Протестируйте дополнение

Важно: Хотя вы можете протестировать свое приложение напрямую с помощью веб-браузера, вам следует в первую очередь протестировать его в надстройках Classroom iframes. Загрузка вашего веб-приложения в iframe может привести к некоторым нетипичным поведениям. Прочитайте нашу страницу руководства по iframe и параметрам запроса для описания каждого iframe. Все инструкции, приведенные в этом пошаговом руководстве, предполагают, что надстройка может использоваться в контексте iframe.

Запустите свой сервер. Затем войдите в Google Classroom как один из ваших тестовых пользователей Teacher . Перейдите на вкладку Classwork и создайте новое Assignment . Выберите надстройку из селектора надстроек . Открывается iframe, и надстройка загружает URI настройки вложения , который вы указали на странице конфигурации приложения Marketplace SDK.

Поздравляем! Вы готовы перейти к следующему шагу: входу пользователей с помощью Google SSO .