Tworzenie dodatku do Classroom

To jest pierwszy przewodnik z serii przewodników dotyczących dodatków do Classroom.

Z tego przewodnika dowiesz się, jak stworzyć aplikację internetową i opublikować ją jako dodatek do Classroom. Kolejne kroki przewodnika rozwijają tę aplikację.

W ramach tego przewodnika wykonaj następujące czynności:

• Utwórz nowy projekt Google Cloud dla swojego dodatku.
• Tworzenie szkieletowej aplikacji internetowej z zastępczymi przyciskami logowania.
• Opublikuj informacje o aplikacji w Google Workspace Marketplace dotyczące dodatku.

Po zakończeniu możesz zainstalować dodatek i wczytać go w elemencie iframe z dodatkami 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 są kontrolowane przez projekty Google Cloud. Poniżej znajdziesz minimalne instrukcje tworzenia i konfigurowania nowego projektu do użycia z Twoim dodatkiem.

Tworzenie projektu

Nowy projekt Google Cloud możesz utworzyć na stronie tworzenia projektu. Możesz podać dowolną nazwę nowego projektu. Kliknij Utwórz.

Utworzenie nowego projektu może chwilę potrwać. Gdy skończysz, wybierz projekt. Możesz go wybrać w menu wyboru projektów u góry ekranu lub kliknąć WYBIERZ PROJEKT w menu powiadomień w prawym górnym rogu.

Dołącz pakiet SDK Google Workspace Marketplace do projektu Google Cloud

Otwórz bibliotekę interfejsów API. Wyszukaj Google Workspace Marketplace SDK. Na liście wyników powinien pojawić się pakiet SDK.

Wybierz kartę pakietu SDK Google Workspace Marketplace i kliknij Włącz.

Konfigurowanie pakietu SDK Google Workspace Marketplace

Google Workspace Marketplace zawiera informacje o tym, za pomocą których użytkownicy i administratorzy mogą instalować Twój dodatek. Aby przejść dalej, skonfiguruj Konfiguracja aplikacji i Informacje o sklepie oraz Ekran zgody OAuth pakietu SDK Marketplace.

Konfiguracja aplikacji

Otwórz stronę Konfiguracja aplikacji pakietu SDK Marketplace. Podaj następujące informacje:

• Ustaw Widoczność aplikacji na Public lub Private.

  • Ustawienie publiczne jest przeznaczone dla aplikacji, które zostaną ostatecznie udostępnione użytkownikom. Przed opublikowaniem aplikacji publicznej dla użytkowników musi ona zostać zatwierdzona, ale możesz określić użytkowników, którzy będą mogli ją zainstalować i przetestować, jako wersję roboczą. Jest to stan przed publikacją, który pozwala przetestować i opracować dodatek przed wysłaniem go do zatwierdzenia.
  • Ustawienie prywatne nadaje się do testów wewnętrznych i programowania. Aplikację prywatną mogą instalować tylko użytkownicy w tej samej domenie, w której został utworzony projekt. Dlatego ustaw widoczność na prywatny tylko wtedy, gdy projekt został utworzony w domenie z subskrypcją Google Workspace for Education. W przeciwnym razie użytkownicy testowi nie będą mogli uruchamiać dodatków do Classroom.

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

• W sekcji Integracja aplikacji wybierz Dodatek do Classroom. Pojawi się prośba o podanie identyfikatora URI bezpiecznej konfiguracji załączników. Jest to URL, który powinien zostać wczytany, gdy użytkownik otworzy Twój dodatek. Na potrzeby tego przewodnika powinna to być właściwość https://<your domain>/addon-discovery.

• Dozwolone prefiksy identyfikatorów URI załączników służą do sprawdzania identyfikatorów URI ustawionych w AddOnAttachment za pomocą metod courses.*.addOnAttachments.create i courses.*.addOnAttachments.patch. Weryfikacja polega na dopasowaniu prefiksu ciągu znaków i 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 protokołu OAuth co na ekranie zgody OAuth w poprzednim kroku.

• Wypełnij odpowiednie pola w sekcji Linki dla deweloperów (w zależności od potrzeb organizacji).

Informacje o aplikacji

W pakiecie SDK Marketplace otwórz stronę Informacje o aplikacji. Podaj następujące informacje:

• W sekcji Szczegóły aplikacji dodaj język lub rozwiń menu obok języka wymienionego już na liście. Podaj nazwę aplikacji i opisy. Pojawią się one na stronie z informacjami o dodatku w Google Workspace Marketplace. Aby zapisać zmiany, kliknij Gotowe.
• Wybierz Kategorię dodatku.
• W sekcji Zasoby graficzne dodaj obrazy do wymaganych pól. Możesz je później zmienić i na razie są to obiekty zastępcze.
• W sekcji Linki pomocy podaj żądane adresy URL. Mogą to być obiekty zastępcze, jeśli w poprzednim kroku ustawisz widoczność aplikacji na Prywatna.

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

Ekran zgody OAuth

Ekran zgody OAuth pojawia się, gdy użytkownik po raz pierwszy autoryzuje aplikację. Wyświetla prośbę o zezwolenie aplikacji na dostęp do ich danych osobowych i informacji o koncie zgodnie z ustawionymi przez Ciebie zakresami.

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

• Ustaw Typ użytkownika na Zewnętrzny. Kliknij Utwórz.
• Na następnej stronie podaj wymagane szczegóły aplikacji i dane kontaktowe. Podaj wszystkie domeny hostujące Twoją aplikację w sekcji Autoryzowane domeny. Kliknij ZAPISZ I KONTYNUUJ.

• Dodaj wszystkie zakresy protokołu OAuth wymagane przez Twoją aplikację internetową. Szczegółowe omówienie zakresów i ich zastosowania znajdziesz w przewodniku po konfiguracji OAuth.

  Aby umożliwić Google wysyłanie parametru zapytania login_hint, musisz zażądać co najmniej 1 z tych zakresów. Bardziej szczegółowe wyjaśnienie tego sposobu działania znajdziesz w naszym przewodniku po konfiguracji OAuth:

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

  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ż wszystkie inne zakresy interfejsów API Google, których aplikacja wymaga od użytkowników.

  Kliknij ZAPISZ I KONTYNUUJ.

• Wymień adresy e-mail wszystkich kont testowych na stronie Użytkownicy testowi. Kliknij ZAPISZ I KONTYNUUJ.

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

Instalowanie dodatku

Możesz teraz zainstalować dodatek, korzystając z linku u góry strony Informacje o aplikacji pakietu SDK Marketplace. Kliknij URL aplikacji u góry strony, aby wyświetlić informacje, a potem wybierz Zainstaluj.

Tworzenie podstawowej aplikacji internetowej

Skonfiguruj szkieletową aplikację internetową z 2 trasami. Kolejne kroki przewodnika rozwijają tę aplikację, więc na razie utwórz tylko stronę docelową dodatku /addon-discovery i przykładową stronę indeksu / dla naszej „witryny firmy”.

Zaimplementuj te 2 punkty końcowe:

• /: wyświetla wiadomość powitalną oraz przycisk zamykający zarówno bieżącą kartę, jak i element iframe dodatku.
• /addon-discovery: wyświetla wiadomość powitalną i 2 przyciski: jeden do zamykania dodatkowego elementu iframe i drugi do otwierania witryny w nowej karcie.

Pamiętaj, że dodajemy przyciski do tworzenia i zamykania okien lub elementów iframe. W następnym przewodniku demonstrują, jak w następnym przewodniku bezpiecznie umieścić użytkownika w nowej karcie na potrzeby autoryzacji.

Utwórz skrypt narzędziowy

Utwórz katalog static/scripts. Utwórz nowy plik addon-utils.js. Dodaj 2 podane niżej 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 Nauczyciel. Otwórz kartę Zadania i utwórz nowy projekt. Wybierz dodatek w selektorze Dodatki. Element iframe otworzy się, a dodatek wczyta identyfikator URI konfiguracji załącznika podany na stronie Konfiguracja aplikacji pakietu SDK Marketplace.

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