Tworzenie dodatku do Classroom

To pierwszy przewodnik z serii przewodników po dodatkach do Classroom.

W tym przewodniku przygotujesz podstawy do opracowania aplikacji internetowej i opublikowania jej jako dodatku do Classroom. W kolejnych krokach przewodnika rozbudujesz tę aplikację.

W ramach tego przewodnika wykonasz te czynności:

• Utworzysz nowy projekt w chmurze Google na potrzeby dodatku.
• Utworzysz szkielet aplikacji internetowej z przyciskami logowania.
• Opublikujesz informacje o dodatku w Google Workspace Marketplace.

Po zakończeniu możesz zainstalować dodatek i załadować go w elemencie iframe dodatków do Classroom.

Wymagania wstępne

Wybierz język, aby zobaczyć odpowiednie wymagania wstępne:

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

Konfigurowanie projektu Google Cloud

Dostęp do interfejsu Classroom API i wymaganych metod uwierzytelniania jest kontrolowany przez projekty Google Cloud. Poniższe instrukcje przeprowadzą Cię przez minimalne kroki wymagane do utworzenia i skonfigurowania nowego projektu do użycia z dodatkiem.

Tworzenie projektu

Utwórz nowy projekt w chmurze Google, otwierając stronę tworzenia projektu. Możesz podać dowolną nazwę nowego projektu. Kliknij Utwórz.

Utworzenie nowego projektu zajmuje kilka chwil. Gdy to zrobisz, be sure to wybierz projekt; możesz go wybrać w menu wyboru projektu u góry ekranu lub kliknąć WYBIERZ PROJEKT w menu powiadomień w prawym górnym rogu.

Dołączanie pakietu SDK Google Workspace Marketplace do projektu Google Cloud

Otwórz przeglądarkę biblioteki interfejsów API. Wyszukaj Google Workspace Marketplace SDK. Pakiet SDK powinien pojawić się na liście wyników.

Wybierz kartę pakietu SDK Google Workspace Marketplace, a następnie kliknij Włącz.

Konfigurowanie pakietu SDK Google Workspace Marketplace

Google Workspace Marketplace udostępnia informacje, za pomocą których użytkownicy i administratorzy mogą zainstalować Twój dodatek. Aby kontynuować, skonfiguruj Konfigurację aplikacji i Informacje o aplikacji oraz Ekran zgody OAuth w pakiecie SDK Marketplace.

Konfiguracja aplikacji

Otwórz stronę Konfiguracja aplikacji w pakiecie SDK Marketplace. Podaj te informacje:

• Ustaw Widoczność aplikacji na Public lub Private.

  • Ustawienie publiczne jest przeznaczone dla aplikacji, które ostatecznie zostaną udostępnione użytkownikom. Zanim aplikacja publiczna zostanie opublikowana dla użytkowników, musi przejść proces zatwierdzania, ale możesz określić użytkowników, którzy mogą ją zainstalować i przetestować jako wersję roboczą. Jest to stan przed publikacją, który umożliwia testowanie i rozwijanie dodatku przed wysłaniem go do zatwierdzenia.
  • Ustawienie prywatne jest odpowiednie do testowania i programowania wewnętrznego. Aplikację prywatną mogą instalować tylko użytkownicy w tej samej domenie, w której utworzono projekt. Dlatego ustaw widoczność na prywatną tylko wtedy, gdy projekt został utworzony w domenie z subskrypcją Google Workspace for Education subskrypcja, w przeciwnym razie użytkownicy testowi nie będą mogli uruchamiać dodatków do Classroom.

• Jeśli chcesz ograniczyć instalację do administratorów domeny, ustaw Ustawienia instalacji na Admin Only install.

• W sekcji Integracja aplikacji wybierz Dodatek do Classroom. Zostanie wyświetlony monit o podanie bezpiecznego identyfikatora URI konfiguracji załącznika. Jest to adres URL, który ma się wczytywać, gdy użytkownik otworzy Twój dodatek. Na potrzeby tego przewodnika powinien to być adres https://<your domain>/addon-discovery.

• Dozwolone prefiksy identyfikatorów URI załączników służą do weryfikowania identyfikatorów URI ustawionych w AddOnAttachmentAddOnAttachment za pomocą metod courses.*.addOnAttachments.createcourses.*.addOnAttachments.create i courses.*.addOnAttachments.patchcourses.*.addOnAttachments.patch. Weryfikacja polega na dosłownym dopasowaniu prefiksu ciągu znaków i obecnie nie pozwala na używanie symboli wieloznacznych. Dodaj co najmniej domenę główną serwera treści, np. https://localhost:5000/ lub https://cdn.myedtech.com/.

• Dodaj te same zakresy OAuth , które zostały podane na ekranie zgody OAuth w poprzednim kroku.

• Wypełnij pola w sekcji Linki dla programistów odpowiednio do swojej organizacji.

Informacje o aplikacji

Otwórz stronę Informacje o aplikacji w pakiecie SDK Marketplace. Podaj te informacje:

• W sekcji Szczegóły aplikacji dodaj język lub rozwiń menu obok języka, który jest już na liście. Podaj nazwę aplikacji i opisy. Będą one widoczne na stronie informacji o dodatku w Google Workspace Marketplace. Aby zapisać, kliknij Gotowe.
• Wybierz kategorię dodatku.
• W sekcji Pliki graficzne podaj obrazy w wymaganych polach. Możesz je później zmienić. Na razie mogą to być symbole zastępcze.
• W sekcji Linki do pomocy podaj wymagane adresy URL. Mogą to być symbole zastępcze, jeśli w poprzednim kroku ustawisz widoczność aplikacji na Prywatny.

Jeśli w poprzednim kroku ustawisz widoczność aplikacji na Prywatny, kliknij OPUBLIKUJ; aplikacja będzie od razu dostępna do zainstalowania. Jeśli ustawisz widoczność aplikacji na Publiczny, dodaj adresy e-mail użytkowników testowych w obszarze Testerzy wersji roboczej i kliknij Zapisz wersję roboczą.

Ekran zgody OAuth

Ekran zgody OAuth pojawia się, gdy użytkownicy po raz pierwszy autoryzują Twoją aplikację. Prosi ich o zezwolenie aplikacji na dostęp do informacji osobistych i informacji o koncie zgodnie z włączonymi przez Ciebie zakresami.

Otwórz stronę tworzenia ekranu zgody OAuth. Podaj te informacje:

• W polu Typ użytkownika wybierz Zewnętrzny. Kliknij Utwórz.
• Na następnej stronie wypełnij wymagane szczegóły aplikacji i dane kontaktowe. W sekcji Autoryzowane domeny podaj wszystkie domeny, w których hostowana jest Twoja aplikacja. Kliknij ZAPISZ I KONTYNUUJ.

• Dodaj wszystkie zakresy OAuth , których wymaga Twoja aplikacja internetowa. Szczegółowe omówienie zakresów i ich przeznaczenia znajdziesz w przewodniku po konfiguracji OAuth.

  Aby Google mogło wysłać parametr zapytania login_hint, musisz poprosić o co najmniej jeden z tych zakresów. Szczegółowe wyjaśnienie tego zachowania znajdziesz w naszym przewodniku po konfiguracji OAuth:

  • https://www.googleapis.com/auth/userinfo.email (już uwzględniony)
  • https://www.googleapis.com/auth/userinfo.profile (już uwzględniony)

  Te zakresy są specyficzne dla dodatków do Classroom:

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

  Uwzględnij też inne zakresy interfejsu Google API, których Twoja aplikacja wymaga od użytkowników.

  Kliknij ZAPISZ I KONTYNUUJ.

• Na stronie Użytkownicy testowi podaj adresy e-mail kont testowych. Kliknij ZAPISZ I KONTYNUUJ.

Sprawdź, czy ustawienia są prawidłowe, a następnie wróć do panelu.

Instalowanie dodatku

Możesz teraz zainstalować dodatek, korzystając z linku u góry strony Informacje o aplikacjiw pakiecie SDK Marketplace. Aby wyświetlić informacje, kliknij Wyświetl w Marketplace u góry strony, a następnie wybierz Zainstaluj.

Tworzenie podstawowej aplikacji internetowej

Skonfiguruj szkielet aplikacji internetowej z 2 trasami. W kolejnych krokach przewodnika rozbudujesz tę aplikację, więc na razie utwórz tylko stronę docelową dodatku /addon-discovery i przykładową stronę główną / dla naszej "witryny firmowej".

Zaimplementuj te 2 punkty końcowe:

• /: wyświetla wiadomość powitalną i przycisk zamykający zarówno bieżącą kartę, jak i element iframe dodatku.
• /addon-discovery: wyświetla wiadomość powitalną i 2 przyciski: jeden zamyka element iframe dodatku, a drugi otwiera witrynę na nowej karcie.

Pamiętaj, że dodajemy przyciski do tworzenia i zamykania okien lub elementu iframe. W następnym przewodniku pokażemy, jak bezpiecznie otworzyć nową kartę na potrzeby autoryzacji.

Tworzenie skryptu narzędziowego

Utwórz katalog static/scripts. Utwórz nowy plik addon-utils.js. Dodaj te 2 funkcje.

/**
 *   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',
  }, '*');
};

Tworzenie tras

Zaimplementuj punkty końcowe /addon-discovery i /.

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

Testowanie dodatku

Uruchom serwer. Następnie zaloguj się w Google Classroom jako jeden z użytkowników testowych nauczycieli. Otwórz kartę Zadania i utwórz nowe zadanie. Wybierz dodatek w selektorze Dodatki. Otworzy się element iframe a dodatek wczyta identyfikator URI konfiguracji załącznika określony na stronie Konfiguracja aplikacji w pakiecie SDK Marketplace.

Gratulacje! Możesz przejść do następnego kroku: logowania użytkowników za pomocą logowania jednokrotnego Google.