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 przyszłości kroki instruktażowe rozwiną tę aplikację.

W ramach tego przewodnika wykonasz te czynności:

• Utwórz nowy projekt Google Cloud dla dodatku.
• Utwórz szkielet aplikacji internetowej z przyciskami logowania zastępczego.
• Opublikuj w Google Workspace Marketplace informacje o swoim dodatku.

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

Ważne: zanim przejdziesz do tych przewodników, przeczytaj przewodnik po konfiguracji projektu i wykonaj kroki wprowadzające w ramach ścieżki dewelopera. Zwróć szczególną uwagę na ustawienie widoczności aplikacji, ponieważ nie można go później zmienić.

Wymagania wstępne

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

Python

W naszym przykładzie w Pythonie używamy platformy Flask. Na stronie Przegląd możesz pobrać kompletny kod źródłowy wszystkich przewodników. Kod do tego konkretnego przewodnika znajdziesz w katalogu /flask/01-basic-app/.

W razie potrzeby zainstaluj Pythona w wersji 3.7 lub nowszej i upewnij się, że dostępny jest znak pip.

python -m ensurepip --upgrade

Zalecamy też skonfigurowanie i aktywowanie nowego wirtualnego środowiska Pythona.

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

Każdy podkatalog z przewodnikami w pobranych przykładach zawiera plik requirements.txt. Wymagane biblioteki możesz szybko zainstalować za pomocą polecenia pip. Aby zainstalować biblioteki wymagane w tym przewodniku, użyj tych poleceń.

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

Node.js

Nasz przykład w Node.js korzysta z platformy Express. Na stronie Przegląd możesz pobrać kompletny kod źródłowy wszystkich przewodników.

W razie potrzeby zainstaluj NodeJS w wersji 16.13 lub nowszej.

Zainstaluj wymagane moduły węzła za pomocą npm.

npm install

Java

W naszym przykładzie w Javie używamy platformy Spring Boot. Na stronie Przegląd możesz pobrać kompletny kod źródłowy wszystkich przewodników.

Zainstaluj Java 11 lub nowszą, jeśli nie masz jej jeszcze na komputerze.

Aplikacje Spring Boot mogą używać Gradle lub Maven do obsługi kompilacji i zarządzania zależnościami. Ten przykład zawiera wrapper Maven, który zapewnia pomyślne kompilowanie bez konieczności instalowania samego narzędzia Maven.

Aby uruchomić podany przykład, w katalogu, do którego został pobrany projekt, uruchom te polecenia. Dzięki temu sprawdzisz, czy masz wymagania wstępne do uruchomienia projektu.

java --version
./mvnw --version

W systemie Windows:

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 Google Cloud na stronie tworzenia projektu. Możesz podać dowolną nazwę nowego projektu. Kliknij Utwórz.

Utworzenie nowego projektu może potrwać kilka minut. Następnie wybierz projekt. Możesz to zrobić w menu wyboru projektu u góry ekranu lub kliknąć WYBIERZ PROJEKT w menu powiadomień w prawym górnym rogu.

Ważne: przed przejściem dalej upewnij się, że masz wybrany odpowiedni projekt.

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

Otwórz Bibliotekę interfejsów API w przeglądarce. 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 listę, za pomocą której użytkownicy i administratorzy instalują Twój dodatek. Aby kontynuować, skonfiguruj konfigurację aplikacji i informacje o aplikacji w sklepie w pakiecie Marketplace SDK oraz ekran zgody OAuth.

Konfiguracja aplikacji

Otwórz stronę Konfiguracja aplikacji w pakiecie 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. Aplikacja publiczna musi przejść proces zatwierdzania, zanim zostanie opublikowana dla użytkowników. Możesz jednak 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 przesłaniem go do zatwierdzenia.
  • Ustawienie prywatne jest odpowiednie do testów wewnętrznych i programowania. Aplikację prywatną mogą zainstalować tylko użytkownicy w tej samej domenie, w której utworzono projekt. Dlatego widoczność prywatną należy ustawić 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.
  Ostrzeżenie: przed zapisaniem sprawdź, czy ustawienie Widoczność aplikacji jest prawidłowe. Po ustawieniu widoczności aplikacji nie można jej zmienić. Aby ustawić inną widoczność aplikacji, musisz utworzyć nowy projekt Google Cloud.

• 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 bezpiecznego identyfikatora URI konfiguracji załącznika. Jest to adres URL, który ma się wczytywać, gdy użytkownik otworzy dodatek. Na potrzeby tego przewodnika powinna to być wartość https://<your domain>/addon-discovery.

• Dozwolone prefiksy identyfikatorów URI załączników służą do weryfikowania identyfikatorów URI ustawionych w AddOnAttachment za pomocą metod courses.*.addOnAttachments.create i courses.*.addOnAttachments.patch. Weryfikacja polega na dosłownym dopasowaniu prefiksu ciągu znaków i nie pozwala obecnie 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.

  Ważne: lista zakresów OAuth określonych w konfiguracji aplikacji musi być zgodna z zakresami wyświetlanymi na ekranie zgody OAuth.

• W sekcji Linki dla deweloperów wypełnij pola odpowiednie dla Twojej organizacji.

Informacje o aplikacji

Otwórz stronę Informacje o aplikacji w pakiecie SDK Marketplace. Podaj następujące 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 wyświetlane na stronie z informacjami o dodatku w Google Workspace Marketplace. Aby zapisać zmiany, kliknij Gotowe.
• Wybierz kategorię dodatku.
• W sekcji Zasoby graficzne podaj obrazy w wymaganych polach. Możesz je później zmienić, a na razie mogą to być symbole zastępcze.
• W sekcji Linki pomocy podaj wymagane adresy URL. Jeśli w poprzednim kroku ustawisz widoczność aplikacji na Prywatna, możesz użyć symboli zastępczych.

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, w obszarze Testerzy wersji roboczych dodaj adresy e-mail testerów i kliknij Zapisz wersję roboczą.

Ważne: jeśli wybierzesz OPUBLIKUJ w przypadku aplikacji o widoczności publicznej, zostanie ona natychmiast przesłana do sprawdzenia przez zespół Marketplace. Zanim aplikacja zostanie dodana do Marketplace, zespół weryfikacyjny musi ją przetestować i zatwierdzić. Zapisz wersje robocze projektu, aby użytkownicy mogli go zainstalować bez sprawdzania. Gdy będziesz gotowy(-a) do przesłania projektu do zatwierdzenia przez zespół Marketplace, możesz kliknąć OPUBLIKUJ WERSJĘ ROBOCZĄ.

Ekran zgody OAuth

Ekran zgody OAuth pojawia się, gdy użytkownicy po raz pierwszy autoryzują Twoją aplikację. Wyświetla się na nim prośba o zezwolenie na dostęp do danych osobowych i informacji o koncie użytkownika w zakresie zakresów, które włączysz.

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 podaj wymagane informacje o aplikacji i dane kontaktowe. W sekcji Autoryzowane domeny podaj domeny, w których jest hostowana Twoja aplikacja. Kliknij ZAPISZ I KONTYNUUJ.

• Dodaj wszystkie zakresy OAuth, których wymaga Twoja aplikacja internetowa. Szczegółowe informacje o zakresach i ich przeznaczeniu 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ędniono)
  • https://www.googleapis.com/auth/userinfo.profile (już uwzględniono)

  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

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

  Kliknij ZAPISZ I KONTYNUUJ.

• Na stronie Test users (Użytkownicy testowi) podaj adresy e-mail wszystkich kont testowych. Kliknij ZAPISZ I KONTYNUUJ.

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

Jak zainstalować dodatek

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

Uwaga: obecnie tylko wybrani użytkownicy będą mogli zainstalować ten dodatek. Jeśli dodatek ma widoczność publiczną, są to tylko użytkownicy wymienieni jako testerzy wersji roboczej. Jeśli dodatek ma widoczność prywatną, są to wszyscy użytkownicy w tej samej domenie co projekt w chmurze.

Tworzenie podstawowej aplikacji internetowej

Skonfiguruj szkielet aplikacji internetowej z 2 trasami. W przyszłości rozbudujemy tę aplikację, więc na razie utwórz stronę docelową dodatku/addon-discovery i stronę indeksu/ dla naszej „witryny firmy”.

Zaimplementuj te 2 punkty końcowe:

• /: wyświetla wiadomość powitalną i przycisk zamykający bieżącą kartę i element iframe dodatku.
• /addon-discovery: wyświetla wiadomość powitalną i 2 przyciski: jeden do zamknięcia elementu iframe dodatku i jeden do otwarcia strony w nowej karcie.

Pamiętaj, że dodajemy przyciski do tworzenia i zamykania okien lub elementu iframe. W kolejnym przewodniku pokażemy, jak bezpiecznie otworzyć nową kartę, na której użytkownik będzie mógł autoryzować aplikację.

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

Python

Konfigurowanie katalogu aplikacji

Na potrzeby tego przykładu strukturę logiki aplikacji przedstawimy jako moduł Pythona. W naszym przykładzie jest to katalog webapp.

Utwórz katalog modułu serwera, np. webapp. Przenieś katalog static do katalogu modułu. Utwórz też katalog template w katalogu modułu. Będą się w nim znajdować pliki HTML.

Utwórz moduł serwera*

Utwórz plik __init__.py w katalogu modułu i dodaj te importy i deklaracje.

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

Następnie utwórz plik do obsługi tras aplikacji internetowej. W naszym przykładzie jest towebapp/routes.py. Wdróż 2 trasy w tym pliku.

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

Zwróć uwagę, że obie nasze trasy przekazują zmienną message do odpowiednich szablonów Jinja. Pomaga to określić, na którą stronę trafił użytkownik.

Tworzenie plików konfiguracji i plików uruchamiania

W katalogu głównym aplikacji utwórz pliki main.py i config.py. Skonfiguruj klucz tajny na urządzeniu 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."

W pliku main.py zaimportuj moduł i uruchom serwer 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

Trasy są rejestrowane w pliku app.js za pomocą tych wierszy.

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

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

Otwórz /01-basic-app/routes/index.js i przejrzyj kod. Ta ścieżka jest osiągana, gdy użytkownik odwiedza witrynę firmy. Trasa renderuje odpowiedź za pomocą indexszablonu Handlebars i przekazuje do niego obiekt danych zawierający zmienne title i message.

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

Otwórz drugą ścieżkę /01-basic-app/routes/classroom-addon.js i przejrzyj kod. Ta ścieżka jest osiągana, gdy użytkownik odwiedza dodatek. Zwróć uwagę, że ta ścieżka korzysta z discoveryszablonu Handlebarsaddon.hbs i dodatkowo z addon.hbsukładuaddon.hbs, aby renderować stronę inaczej niż witryna firmy.

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

Java

Przykładowy kod w Javie korzysta z modułów do pakowania kolejnych kroków przewodnika. Ponieważ jest to pierwszy przewodnik, kod znajduje się w module step_01_basic_app. Nie oczekujemy, że zaimplementujesz projekt za pomocą modułów. Sugerujemy raczej, abyś w miarę wykonywania kolejnych kroków w przewodniku rozwijał jeden projekt.

Utwórz klasę kontrolera, Controller.java w tym projekcie przykładowym, aby zdefiniować punkty końcowe. W tym pliku zaimportuj adnotację @GetMapping z zależności spring-boot-starter-web.

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

Umieść adnotację kontrolera frameworka Spring nad definicją klasy, aby wskazać jej przeznaczenie.

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

Następnie zaimplementuj 2 trasy i dodatkową trasę do obsługi błędów.

/** 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

Ważne: aplikację możesz testować bezpośrednio w przeglądarce, ale przede wszystkim powinnaś(-eś) to robić w ramkach iframe dodatków do Classroom. Wczytywanie aplikacji internetowej w ramce iframe może powodować nietypowe zachowania. Opis każdego elementu iframe znajdziesz na naszej stronie z przewodnikiem po elementach iframe i parametrach zapytań. Wszystkie instrukcje podane w tym przewodniku zakładają, że dodatek jest użyteczny w kontekście elementu iframe.

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

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