Przewodniki

Ta seria przewodników ilustruje wszystkie elementy działającego dodatku do Google Classroom. Każdy krok przewodnika dotyczy konkretnych koncepcji, które są wdrażane w ramach jednej aplikacji internetowej. Ma ona pomóc Ci w skonfigurowaniu, uruchomieniu i wdrożeniu funkcjonalnego dodatku.

Dodatek musi wchodzić w interakcje z projektem Google Cloud. Jeśli nie znasz Google Cloud, zalecamy przeczytanie przewodników dla początkujących. W konsoli Google Cloud możesz zarządzać danymi logowania, dostępem do interfejsu API i pakietem SDK Google Workspace Marketplace. Więcej informacji o pakiecie SDK Marketplace znajdziesz na stronie przewodnika Google Workspace Marketplace.

W tym przewodniku znajdziesz informacje na te tematy:

  • Użyj Google Cloud, aby utworzyć stronę, która będzie wyświetlana w elemencie iframe w Classroom.
  • Dodaj logowanie jednokrotne Google i zezwól użytkownikom na logowanie się.
  • Wykonaj wywołania interfejsu API, aby dołączyć dodatek do projektu.
  • Spełnij najważniejsze wymagania dotyczące przesyłania dodatków i wymagane funkcje.

W tym przewodniku zakładamy, że znasz podstawy programowania i koncepcje związane z tworzeniem stron internetowych. Zanim zaczniesz korzystać z przewodników, zdecydowanie zalecamy zapoznanie się z przewodnikiem po konfiguracji projektu. Ta strona zawiera ważne szczegóły konfiguracji, które nie są w pełni omówione w przewodnikach.

Przykładowe implementacje

Pełny przykład referencyjny jest dostępny w Python. Częściowe implementacje są też dostępne w językach Java i Node.js. Te implementacje są źródłem przykładowego kodu, który znajdziesz na kolejnych stronach.

Gdzie pobrać

Przykłady w językach Python i Java są dostępne w repozytoriach GitHub:

Przykładowy kod Node.js można pobrać jako plik ZIP:

Wymagania wstępne

Aby przygotować nowy projekt dodatku, zapoznaj się z sekcjami poniżej.

Certyfikat HTTPS

Aplikację możesz hostować w dowolnym środowisku programistycznym, ale dodatek do Classroom jest dostępny tylko w https://. Dlatego musisz mieć serwer z szyfrowaniem SSL, aby wdrożyć aplikację lub przetestować ją w ramce iframe dodatku.

Możesz używać localhost z certyfikatem SSL. Jeśli musisz utworzyć certyfikat na potrzeby lokalnego programowania, rozważ użycie mkcert.

Projekt Google Cloud

Musisz skonfigurować projekt Google Cloud, aby można było używać go w tych przykładach. Więcej informacji o niezbędnych krokach znajdziesz w przewodniku tworzenia projektu Google Cloud. W sekcji Konfigurowanie projektu Google Cloud w pierwszym przewodniku znajdziesz też szczegółowe instrukcje dotyczące konfiguracji.

Po zakończeniu pobierz identyfikator klienta OAuth 2.0 jako plik JSON. Musisz dodać ten plik danych logowania do rozpakowanego katalogu z przykładem. Więcej informacji o konkretnych lokalizacjach znajdziesz w sekcji Informacje o plikach.

Dane logowania OAuth

Aby utworzyć nowe dane logowania OAuth:

  • Otwórz stronę Dane logowania Google Cloud. Sprawdź, czy u góry ekranu masz wybrany odpowiedni projekt.
  • Kliknij UTWÓRZ DANE LOGOWANIA i z menu wybierz Identyfikator klienta OAuth.
  • Na następnej stronie:
    • Jako Typ aplikacji wybierz Aplikacja internetowa.
    • W sekcji Autoryzowane identyfikatory URI przekierowania kliknij DODAJ URI. Dodaj pełną ścieżkę trasy wywołania zwrotnego dla swojej aplikacji. Na przykład https://my.domain.com/auth-callback lub https://localhost:5000/callback. Tę ścieżkę utworzysz i obsłużysz w dalszej części tego przewodnika. W każdej chwili możesz edytować takie trasy lub dodawać nowe.
    • Kliknij UTWÓRZ.
  • Następnie wyświetli się okno z nowo utworzonymi danymi logowania. Wybierz opcję POBIERZ JSON. Skopiuj pobrany plik JSON do katalogu serwera.

Wymagania wstępne dotyczące poszczególnych języków

Najnowszą listę wymagań wstępnych znajdziesz w pliku README w każdym repozytorium.

Python

W naszym przykładzie w Pythonie używamy platformy Flask. Pełny kod źródłowy możesz pobrać z podanych linków.

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

python3 -m ensurepip --upgrade

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

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

W każdym podkatalogu z przewodnikami w pobranych przykładach znajduje się plik requirements.txt. Wymagane biblioteki możesz szybko zainstalować za pomocą polecenia pip. Aby zainstalować biblioteki wymagane w pierwszym 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 architektury Express. Pełny kod źródłowy możesz pobrać z podanych linków.

Ten przykład wymaga Node.js 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. Pełny kod źródłowy możesz pobrać z podanych linkó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.

W katalogu, w którym masz pobrany lub sklonowany projekt, uruchom te polecenia, aby sprawdzić, czy masz wymagania wstępne do uruchomienia projektu.

java --version
./mvnw --version

W systemie Windows:

java -version
mvnw.cmd --version

Informacje o plikach

W sekcjach poniżej opisujemy układ przykładowych katalogów.

Nazwy katalogów

Każde repozytorium zawiera kilka katalogów, których nazwy zaczynają się od cyfry, np. /01-basic-app/. Liczby odpowiadają konkretnym krokom instrukcji. Każdy katalog zawiera w pełni funkcjonalną aplikację internetową, która implementuje funkcje opisane w danym przewodniku. Na przykład katalog /01-basic-app/ zawiera ostateczną implementację przewodnika Tworzenie dodatku.

Zawartość katalogu

Zawartość katalogu różni się w zależności od języka implementacji:

Python

  • Katalog główny zawiera te pliki:

    • main.py – punkt wejścia aplikacji w Pythonie. W tym pliku określ konfigurację serwera, której chcesz używać, a następnie uruchom go, aby rozpocząć działanie serwera.
    • requirements.txt – moduły Pythona wymagane do uruchomienia aplikacji internetowej. Można je zainstalować automatycznie za pomocą pip install -r requirements.txt.

    • client_secret.json – plik z tajnym kluczem klienta pobrany z Google Cloud. Pamiętaj, że nie jest to uwzględnione w przykładzie archiwum. Musisz zmienić nazwę pobranego pliku z danymi logowania i skopiować go do każdego katalogu głównego.

  • config.py – opcje konfiguracji serwera Flask.

  • webapp katalog zawiera treści aplikacji internetowej. Obejmuje to:

  • Katalog /templates/ z szablonami Jinja dla różnych stron.

  • Katalog /static/ z obrazami, plikami CSS i pomocniczymi plikami JavaScript.

  • routes.py – metody obsługi tras aplikacji internetowej.

  • __init__.py – inicjator modułu webapp. Ten inicjator uruchamia serwer Flask i wczytuje opcje konfiguracji ustawione w config.py.

  • Dodatkowe pliki wymagane w ramach danego kroku przewodnika.

Node.js

Każdy krok instrukcji znajdziesz w osobnym podfolderze.<step> Każdy krok zawiera:

  • Pliki statyczne, takie jak JavaScript, CSS i obrazy, znajdują się w folderze ./<step>/public.
  • Routery ekspresowe znajdują się w folderach ./<step>/routes.
  • Szablony HTML znajdują się w folderach ./<step>/views.
  • Aplikacja serwera to ./<step>/app.js.

Java

Katalog projektu zawiera te elementy:

  • Katalog src.main zawiera kod źródłowy i konfigurację umożliwiające prawidłowe uruchomienie aplikacji. Ten katalog zawiera:java.com.addons.spring – katalog zawierający pliki Application.java i Controller.java. Plik Application.java odpowiada za uruchamianie serwera aplikacji, a plik Controller.java obsługuje logikę punktu końcowego. + resources zawiera katalog templates z plikami HTML i JavaScript. Zawiera też plik application.properties, który określa port, na którym ma działać serwer, ścieżkę do pliku magazynu kluczy i ścieżkę do katalogu templates. Ten przykład zawiera plik magazynu kluczy w katalogu resources. Możesz go przechowywać w dowolnym miejscu, ale pamiętaj, aby odpowiednio zaktualizować ścieżkę w pliku application.properties.
    • Plik pom.xml zawiera informacje potrzebne do utworzenia projektu i określenia wymaganych zależności.
    • .gitignore zawiera nazwy plików, których nie należy przesyłać do Gita. Pamiętaj, aby dodać ścieżkę do magazynu kluczy w tym miejscu: .gitignore. W podanym przykładzie jest to secrets/*.p12 (cel użycia magazynu kluczy omówimy w sekcji poniżej). W przypadku instrukcji 2 i kolejnych podaj też ścieżkę do pliku client_secret.json, aby mieć pewność, że nie uwzględnisz w zdalnym repozytorium swoich informacji poufnych. W przypadku instrukcji 3 i kolejnych należy dodać ścieżkę do pliku bazy danych H2 i fabryki magazynu danych. Więcej informacji o konfigurowaniu tych magazynów danych znajdziesz w trzecim przewodniku dotyczącym obsługi powracających wizyt.
    • mvnw i mvnw.cmd to pliki wykonywalne narzędzia Maven Wrapper dla systemów Unix i Windows. Na przykład uruchomienie polecenia ./mvnw --version w systemie Unix spowoduje wyświetlenie wersji Apache Maven i innych informacji.
    • Katalog .mvn zawiera konfigurację narzędzia Maven Wrapper.

Uruchamianie przykładowego serwera

Aby przetestować serwer, musisz go uruchomić. Aby uruchomić przykładowy serwer w wybranym języku, postępuj zgodnie z tymi instrukcjami:

Python

Dane uwierzytelniające OAuth

Utwórz i pobierz dane logowania OAuth w sposób opisany wcześniej. Umieść plik JSON w katalogu głównym obok pliku uruchamiającego serwer aplikacji.

Konfigurowanie serwera

Serwer internetowy możesz uruchomić na kilka sposobów. Na końcu pliku Pythona dodaj jeden z tych wierszy:

  1. Niezabezpieczone localhost. Pamiętaj, że ta opcja nadaje się tylko do bezpośredniego testowania w oknie przeglądarki. Niezabezpieczonych domen nie można wczytać w elemencie iframe dodatku do Classroom.

    if __name__ == "__main__":
  # Disable OAuthlib's HTTPs verification.
  os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"

  # Run the web app at http://localhost:5000.
  app.run(debug=True)

  2. Zabezpiecz localhost Musisz określić krotkę plików kluczy SSL dla argumentu ssl_context.

    if __name__ == "__main__":
  # Run the web app at https://localhost:5000.
  app.run(host="localhost",
          ssl_context=("localhost.pem", "localhost-key.pem"),
          debug=True)

  3. serwer Gunicorn; Jest to odpowiednie rozwiązanie w przypadku serwera gotowego do wdrożenia w środowisku produkcyjnym lub wdrożenia w chmurze. Zalecamy ustawienie zmiennej środowiskowej PORT do użycia z tą opcją uruchamiania.

    if __name__ == "__main__":
  # Run the web app at https://<your domain>:<server_port>.
  # Defaults to https://<your domain>:8080.
  server_port = os.environ.get("PORT", "8080")
  app.run(debug=True, port=server_port, host="0.0.0.0")

Uruchamianie serwera

Uruchom aplikację w Pythonie, aby uruchomić serwer skonfigurowany w poprzednim kroku.

python main.py

Kliknij wyświetlony adres URL, aby wyświetlić aplikację internetową w przeglądarce i sprawdzić, czy działa prawidłowo.

Node.js

Konfigurowanie serwera

Aby uruchomić serwer przez HTTPS, musisz utworzyć certyfikat własny, który będzie używany do uruchamiania aplikacji przez HTTPS. Te dane logowania powinny zostać zapisane jako sslcert/cert.pem i sslcert/key.pem w folderze głównym repozytorium. Aby przeglądarka je zaakceptowała, może być konieczne dodanie tych kluczy do łańcucha kluczy systemu operacyjnego.

Upewnij się, że w pliku *.pem znajduje się .gitignore, ponieważ nie chcesz zatwierdzać pliku w systemie Git.

Uruchamianie serwera

Aplikację możesz uruchomić za pomocą tego polecenia, zastępując step01 prawidłowym krokiem, który chcesz uruchomić jako serwer (np. step01 dla 01-basic-app i step02 dla 02-sign-in).

npm run step01

lub

npm run step02

Spowoduje to uruchomienie serwera WWW pod adresem https://localhost:5000.

Możesz zakończyć działanie serwera, wpisując w terminalu Control + C.

Java

Konfigurowanie serwera

Aby uruchomić serwer przez HTTPS, musisz utworzyć certyfikat własny, który będzie używany do uruchamiania aplikacji przez HTTPS.

Do programowania lokalnego możesz użyć narzędzia mkcert. Po zainstalowaniu mkcert te polecenia wygenerują lokalnie przechowywany certyfikat do uruchamiania przez HTTPS.

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

W tym przykładzie plik magazynu kluczy znajduje się w katalogu zasobów. Możesz go przechowywać w dowolnym miejscu, ale pamiętaj, aby odpowiednio zaktualizować ścieżkę w pliku application.properties. Nazwa domeny to domena, w której prowadzisz projekt (np. localhost).

Upewnij się, że w pliku *.p12 znajduje się .gitignore, ponieważ nie chcesz zatwierdzać pliku w systemie Git.

Uruchamianie serwera

Uruchom serwer, wykonując metodę main w pliku Application.java. Na przykład w IntelliJ możesz kliknąć prawym przyciskiem myszy Application.java > Run 'Application' w katalogu src/main/java/com/addons/spring lub otworzyć plik Application.java, aby kliknąć zieloną strzałkę po lewej stronie sygnatury metody main(String[] args). Możesz też uruchomić projekt w oknie terminala:

./mvnw spring-boot:run

lub w systemie Windows:

mvnw.cmd spring-boot:run

Spowoduje to uruchomienie serwera na https://localhost:5000 lub na porcie określonym w application.properties.