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

Это первое пошаговое руководство из серии руководств по использованию дополнений для Classroom.

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

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

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

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

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

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

python -m ensurepip --upgrade

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

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

npm install

java --version
./mvnw --version

java -version
mvnw.cmd --version

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Установите параметр «Установка Admin Only install если хотите ограничить установку только администраторами домена.

• В разделе «Интеграция с приложениями» выберите надстройку Classroom . Вам будет предложено ввести защищенный 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 на предыдущем шаге.

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

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

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

• В разделе «Подробности приложения» добавьте язык или разверните раскрывающийся список рядом с уже указанным языком. Укажите название приложения и описание; они отобразятся на странице вашего дополнения в магазине Google Workspace Marketplace. Нажмите «Готово» , чтобы сохранить.
• Выберите категорию для вашего дополнения.
• В разделе «Графические ресурсы» укажите изображения для необходимых полей. Их можно будет изменить позже, а пока они могут служить в качестве заполнителей.
• В разделе «Ссылки поддержки» укажите запрашиваемые URL-адреса. Если на предыдущем шаге вы установили для приложения режим «Частный» , вы можете использовать в качестве заполнителей эти адреса.

Если на предыдущем шаге вы установили видимость приложения на «Частное» , нажмите «ОПУБЛИКОВАТЬ» ; ваше приложение сразу же станет доступно для установки. Если вы установили видимость приложения на «Общедоступное» , добавьте адреса электронной почты в раздел «Тестировщики черновиков» для всех тестировщиков и нажмите «Сохранить черновик» .

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

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

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

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

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

  Для отправки параметра запроса login_hint необходимо запросить как минимум одну из следующих областей действия (scopes). Более подробное объяснение этого поведения доступно в нашем руководстве по настройке 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 , которые требуются вашему приложению от конечных пользователей.

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

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

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

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

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

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

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

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

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.")

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."

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)

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

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

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

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

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

@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";
}

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

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

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