Tworzenie dodatku do Classroom

To jest pierwszy przewodnik po dodatkach do Classroom. które zrecenzować w naszym serwisie.

Z tego przewodnika dowiesz się, jak przygotować aplikację internetową i opublikować go jako dodatek do Classroom. Przyszłe kroki przewodnika rozwiń 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 załadować go Element iframe dodatków do Classroom.

Ważne: zanim skorzystasz z tych instrukcji, zapoznaj się z konfiguracją projektu i wykonaj czynności wprowadzające do ścieżki dewelopera. Zapłać należy zwrócić szczególną uwagę na ustawienie widoczności aplikacji, ponieważ nie można później.

Wymagania wstępne

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

Python

Nasz przykład w Pythonie korzysta z platformy Flask. Możesz pobrać pełną wersję kod źródłowy we wszystkich przewodnikach na stronie Przegląd. Kod dla tej wartości znajdziesz w katalogu /flask/01-basic-app/.

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

python -m ensurepip --upgrade

Zalecamy też skonfigurowanie i aktywowanie nowego wirtualnego serwera w Pythonie. dla środowiska.

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

Każdy podkatalog przewodnika w pobranych przykładach zawiera element requirements.txt Wymagane biblioteki możesz szybko zainstalować za pomocą pip Użyj tego kodu, aby zainstalować wymagane biblioteki .

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

Node.js

W naszym przykładzie ze środowiskiem Node.js korzystamy z platformy Express. Możesz pobrać pełny kod źródłowy we wszystkich instrukcjach na stronie Przegląd.

W razie potrzeby zainstaluj NodeJS w wersji 16.13 lub nowszej.

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

npm install

Java

Nasz przykład w Javie korzysta ze platformy Spring Boot. Możesz pobrać pełny kod źródłowy wszystkich instrukcji na stronie Przegląd.

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

Aplikacje Spring Boot mogą używać Gradle lub Maven do obsługi kompilacji i zarządzania nimi zależności. Ten przykład obejmuje otokę Maven, która zapewnia powodzenie kompilacji bez konieczności instalowania samego narzędzia Maven.

Aby móc uruchomić podany przykład, uruchom następujące polecenia w w którym został pobrany projekt, aby upewnić się, że masz jakie są wymagania wstępne do uruchomienia projektu.

java --version
./mvnw --version

Lub w systemie Windows:

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 instrukcje, jak to zrobić. minimalną liczbę kroków do utworzenia i skonfigurowania nowego projektu do użycia Google Analytics.

Tworzenie projektu

Nowy projekt Google Cloud możesz utworzyć na stronie tworzenia projektu. Dostępne opcje i wpisać dowolną nazwę nowego projektu. Kliknij Utwórz.

Utworzenie nowego projektu może chwilę potrwać. Gdy to zrobisz, pamiętaj, aby wybrać projekt; możesz go wybrać w selektorze projektów z menu u góry ekranu lub kliknij WYBIERZ PROJEKT menu powiadomień w prawym górnym rogu.

Ważne: zanim przejdziesz dalej, sprawdź, czy został wybrany właściwy projekt.

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

Otwórz bibliotekę 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 i kliknij Włącz.

Konfigurowanie pakietu SDK Google Workspace Marketplace

Google Workspace Marketplace zawiera informacje, za pomocą których użytkownicy administratorzy zainstalują Twój dodatek. Skonfiguruj Konfiguracja aplikacji i sklep w pakiecie SDK Marketplace Listing, a także ekran akceptacji OAuth, aby przejść dalej.

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 opublikowane. użytkownikom. Aplikacja publiczna musi najpierw przejść proces zatwierdzenia dla użytkowników, ale możesz określić użytkowników, którzy będą mogli przetestuj ją jako Wersję roboczą. Jest to stan przed publikacją, aby przetestować i opracować dodatek, zanim prześlesz go do zatwierdzenia.
  • Ustawienie prywatne nadaje się do testów wewnętrznych i programowania. O Aplikacje prywatne mogą instalować tylko użytkownicy w tej samej domenie Utworzono projekt. Z tego powodu należy ustawić widoczność na prywatną tylko w przypadku, gdy projekt został utworzony w domenie w Google Workspace for Education. subskrypcji. W przeciwnym razie użytkownicy testowi nie będą mogli uruchomić tej usługi. Dodatki do Classroom.
  .
  Ostrzeżenie: przed zapisu. Po ustawieniu widoczności aplikacji nie można jej zmienić. Ty musi utworzyć nowy projekt Google Cloud, aby ustawić inną widoczność aplikacji.

• Ustaw Ustawienia instalacji na Admin Only install, jeśli chcesz ograniczenie instalacji do administratorów domeny.

• W sekcji Integracja aplikacji wybierz Dodatek do Classroom. To już pojawi się prośba o podanie bezpiecznego identyfikatora URI konfiguracji załączników; to URL, zostanie załadowany, gdy użytkownik otworzy dodatek. Na potrzeby niniejszego dokumentu powinien być 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ą funkcji courses.*.addOnAttachments.create oraz courses.*.addOnAttachments.patch. Weryfikacja jest literałem dopasowania przedrostka ciągu i nie zezwala na użycie w tym miejscu symboli wieloznacznych obecnie się znajdujesz. Dodaj przynajmniej domenę główną serwera treści, taką jak https://localhost:5000/ lub https://cdn.myedtech.com/.

• Dodaj te same zakresy protokołu OAuth co na ekranie akceptacji OAuth w w poprzednim kroku.

  Ważne: lista zakresów OAuth określonych w konfiguracji aplikacji musi zgodne z tymi wyświetlanymi na ekranie zgody OAuth.

• Wypełnij pola odpowiednie dla Twojej organizacji w sekcji Programista Linki.

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ęzyk, który jest już na liście. Podać nazwę i opisy aplikacji; ich będą widoczne 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. Mogą one można zmienić później i mogą być obiektami zastępczymi.
• W sekcji Linki pomocy wpisz żądane adresy URL. Mogą to być zastępcze, jeśli w poprzedniej sekcji widoczność aplikacji została ustawiona na Prywatna. krok po kroku.

Jeśli w poprzednim kroku ustawisz widoczność aplikacji na Prywatna, kliknij PUBLISH; od razu będzie można ją zainstalować. Jeśli ustawisz parametr Widoczność aplikacji jako Publiczna – dodaj adresy e-mail w obszarze Testerzy wersji roboczych dla wszystkich użytkowników testowych i kliknij Zapisz wersję roboczą.

Ważne: wybranie opcji OPUBLIKUJ w przypadku aplikacji z widocznością publiczną spowoduje natychmiast ją do sprawdzenia przez zespół Marketplace. zespół sprawdzający musi przetestować i zatwierdzić aplikację, zanim będzie można ją dodać do Rynek. Aby utworzyć projekt, zapisz jego wersje robocze które użytkownicy testowi mogą zainstalować bez sprawdzania. Możesz wybrać opcję OPUBLIKUJ WERSJĘ ROBOCZĄ gdy wszystko będzie gotowe, gdy zespół Marketplace będzie mógł go zaakceptować.

Ekran zgody OAuth

Ekran zgody OAuth pojawia się, gdy użytkownik po raz pierwszy autoryzuje aplikację. Proponuje pozwala aplikacji na dostęp do ich danych osobowych i informacji o koncie. zależy od wybranych przez Ciebie zakresów.

Otwórz stronę tworzenia ekranu zgody OAuth. Podaj te informacje: 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ą. Zobacz artykuł OAuth przewodnika po konfiguracji, w którym znajdziesz szczegółowy opis zakresów i ich celów.

  Musisz poprosić o co najmniej 1 z poniższych zakresów, aby móc korzystać z usługi Google wyślij parametr zapytania login_hint. Bardziej szczegółowe wyjaśnienie 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

  Dołącz też wszelkie inne zakresy interfejsów API Google, których wymaga Twoja aplikacja. 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.

Jak zainstalować dodatek

Dodatek możesz teraz zainstalować, klikając link u góry Strona Informacje o aplikacji w pakiecie SDK Marketplace. Kliknij ikonę aplikacji adres URL na górze strony, aby zobaczyć informacje, a potem kliknij Zainstaluj.

Uwaga: obecnie tylko określeni użytkownicy będą mogli zainstalować ten dodatek. Jeśli Twój dodatek jest widoczny publicznie, wśród tych użytkowników znajdują się tylko użytkownicy oznaczeni jako wersja robocza Testerzy. Jeśli dodatek ma widoczność prywatny, to tutaj znajdują się użytkownicy w w tej samej domenie co projekt Cloud.

Tworzenie podstawowej aplikacji internetowej

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

Zaimplementuj te 2 punkty końcowe:

• /: wyświetla wiadomość powitalną i przycisk zamykania bieżącej karty oraz w elemencie iframe dodatku.
• /addon-discovery: wyświetla wiadomość powitalną i 2 przyciski: jeden do zamykania z dodatkowym elementem iframe, a drugi do otwierania witryny w nowej karcie.

Pamiętaj, że dodajemy przyciski do tworzenia i zamykania okien lub elementów iframe. Te zademonstruj metodę bezpiecznego wydzielenia użytkownika na nową kartę, na której w następnym przewodniku.

Utwórz skrypt narzędziowy

Utwórz katalog static/scripts. Utwórz nowy plik addon-utils.js. Dodaj parametr po 2 funkcjach.

/**
 *   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 skonstruuj logikę aplikacji jako z modułu Python. To jest katalog webapp z podanego przez nas przykładu.

Utwórz katalog dla modułu serwera, np. webapp. Przenieś static do katalogu modułu. Tworzenie katalogu template w katalogu modułów. pliki HTML.

Tworzenie modułu serwera*

Utwórz plik __init__.py w katalogu modułów i dodaj do niego importu i deklaracji.

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. To jest webapp/routes.py. Wdróż 2 trasy w tej .

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 nasze trasy przekazują zmienną message do swoich Szablony Jinja. Pozwala to ustalić, na którą stronę trafił użytkownik.

Tworzenie plików konfiguracji i uruchamiania

W katalogu głównym aplikacji utwórz main.py oraz config.py . Skonfiguruj tajny klucz w 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."

Zaimportuj moduł do pliku main.py 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 w następujących wierszach.

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

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

Otwórz aplikację /01-basic-app/routes/index.js i sprawdź kod. Ta trasa jest gdy użytkownik odwiedza witrynę firmy. Trasa renderuje za pomocą szablonu index Handlebars i przekazuje szablonowi 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ą trasę /01-basic-app/routes/classroom-addon.js i sprawdź kod. Do tej trasy można dotrzeć, gdy użytkownik korzysta z dodatku. Uwaga że ta trasa korzysta z szablonu discovery Handlebars oraz dodatkowo Zastosowanie układu addon.hbs do renderowania strony w inny sposób niż w przypadku firmy witryny.

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 używa modułów do łączenia instrukcji z sekwencją. kroków. To pierwszy przewodnik, więc kod znajduje się w sekcji Moduł step_01_basic_app. nie należy spodziewać się wdrożenia projektu z użyciem modułów; lepiej tworzyć na podstawie jednego projektu, podczas wykonywania poszczególnych czynności.

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

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

Uwzględnij adnotację kontrolera Spring platformy nad klasą definicja wskazująca przeznaczenie klasy.

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

Następnie zaimplementuj dwie 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: chociaż możesz przetestować aplikację bezpośrednio w przeglądarce, należy testować go głównie w elementach iframe dodatków do Classroom. Wczytuję aplikacja internetowa w elemencie iframe może powodować pewne nietypowe zachowania. Przeczytaj nasze elementy iframe i parametrów zapytań. Wszystkie podanych w tym przewodniku przy założeniu, że dodatku można używać w kontekście elementu iframe.

Uruchom serwer. Następnie zaloguj się w Google Classroom jako jeden z uczniów. z Nauczyciele – użytkownicy testowi. Otwórz kartę Zadania i utwórz nowe Cesja. Wybierz dodatek w selektorze Dodatki. Element iframe otworzy się a dodatek wczyta identyfikator URI konfiguracji załączników określony w na stronie Konfiguracja aplikacji pakietu SDK Marketplace.

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