Przewodniki

Ta seria przewodników ilustruje wszystkie elementy działającego dodatku do Classroom. Każdy krok przewodnika dotyczy konkretnych pojęć i ich implementacji w jednej aplikacji internetowej. Celem jest pomoc w skonfigurowaniu i uruchomieniu działającego dodatku.

Twój dodatek musi wchodzić w interakcję 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 po tworzeniu ofert w Google Workspace Marketplace.

W przewodniku znajdziesz te tematy:

• Tworzenie strony w Google Cloud, która będzie wyświetlana w elemencie iframe w Classroom.
• Dodawanie logowania jednokrotnego Google i umożliwianie użytkownikom logowania się.
• Wywoływanie interfejsu API w celu dołączenia dodatku do zadania.
• Spełnianie najważniejszych wymagań dotyczących przesyłania dodatków i wymaganych funkcji.

W tym przewodniku zakładamy, że znasz podstawy programowania i tworzenia stron internetowych. Zanim zaczniesz korzystać z przewodników, zdecydowanie zalecamy przeczytanie przewodnika po konfiguracji projektu. Ta strona zawiera ważne informacje o konfiguracji, które nie są w pełni omówione w przewodnikach.

Przykładowe implementacje

Kompletny przykład referencyjny jest dostępny w Pythonie. Częściowe implementacje są też dostępne w Javie i Node.js. Te implementacje są źródłami przykładowego kodu, który znajdziesz na kolejnych stronach.

Gdzie pobrać

Przykłady w Pythonie i Javie są dostępne w repozytoriach GitHub:

• Repozytorium Pythona

• Repozytorium Javy

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

• Archiwum Node.js

Wymagania wstępne

Aby przygotować nowy projekt dodatków, zapoznaj się z tymi sekcjami.

Certyfikat HTTPS

Aplikację możesz hostować w dowolnym środowisku programistycznym, ale dodatek do Classroom jest dostępny tylko przez https://. Dlatego do wdrożenia aplikacji lub przetestowania jej w elemencie iframe dodatku potrzebujesz serwera z szyfrowaniem SSL.

Możesz używać localhost z certyfikatem SSL. Jeśli musisz utworzyć certyfikat do lokalnego programowania, rozważ użycie narzędzia mkcert.

Projekt Google Cloud

Musisz skonfigurować projekt Google Cloud do użycia z tymi przykładami. Więcej informacji o niezbędnych krokach znajdziesz w przewodniku po tworzeniu projektu Google Cloud. W sekcji Konfigurowanie projektu Google Cloud w pierwszym przewodniku znajdziesz też informacje o konkretnych działaniach konfiguracyjnych.

Gdy skończysz, pobierz identyfikator klienta OAuth 2.0 jako plik JSON. Musisz dodać ten plik danych logowania do rozpakowanego katalogu z przykładem. Konkretne lokalizacje znajdziesz w sekcji Interpretowanie plików.

Dane logowania OAuth

Ważne: Twoja aplikacja internetowa musi używać danych logowania OAuth 2.0 zarządzanych w Google Cloud.

Aby utworzyć nowe dane logowania OAuth, wykonaj te czynności:

• Otwórz stronę danych logowania Google Cloud. Upewnij się, że u góry ekranu masz wybrany odpowiedni projekt.
• Kliknij UTWÓRZ DANE LOGOWANIA i w menu wybierz Identyfikator klienta OAuth.
• Na następnej stronie:
  • Ustaw Typ aplikacji na Aplikacja internetowa.
  • W sekcji Autoryzowane identyfikatory URI przekierowania kliknij DODAJ URI. Dodaj pełną ścieżkę do trasy wywołania zwrotnego w aplikacji. Na przykład https://my.domain.com/auth-callback lub https://localhost:5000/callback. Tę trasę utworzysz i obsłużysz później w tym przewodniku. W każdej chwili możesz edytować te trasy lub dodawać ich więcej.
  • Kliknij UTWÓRZ.
• Otworzy 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

Nasz przykład w Pythonie korzysta z 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 jest dostępny 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 przewodnika w pobranych przykładach znajduje się plik requirements.txt. Wymagane biblioteki możesz szybko zainstalować za pomocą pip. Aby zainstalować wymagane biblioteki na potrzeby pierwszego przewodnika, 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. 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 Node za pomocą npm.

npm install

Java

Nasz przykład w Javie korzysta z platformy Spring Boot. Pełny kod źródłowy możesz pobrać z podanych linków.

Jeśli nie masz jeszcze zainstalowanej Javy 11 lub nowszej, zainstaluj ją.

Aplikacje Spring Boot mogą używać Gradle lub Maven do obsługi kompilacji i zarządzania zależnościami. Ten przykład zawiera otokę Maven, która zapewnia pomyślną kompilację bez konieczności instalowania samego Mavena.

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

java --version
./mvnw --version

Lub w systemie Windows:

java -version
mvnw.cmd --version

Interpretowanie plików

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

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 przewodnika. Każdy katalog zawiera w pełni funkcjonalną aplikację internetową, która implementuje funkcje opisane w danym przewodniku. Na przykład /01-basic-app/ katalog 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 uruchomić serwer.
  • 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 on uwzględniony w archiwum z przykładem. Musisz zmienić nazwę pobranego pliku danych logowania i skopiować go do każdego katalogu głównego.

    Ważne: zanim uruchomisz przykłady, musisz podać plik z tajnym kluczem klienta z swojego projektu w chmurze Google.

• config.py – opcje konfiguracji serwera Flask.

• Katalog webapp zawiera treści aplikacji internetowej. Obejmuje on:

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

• Katalog /static/ z obrazami, 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 pliku config.py.

• Dodatkowe pliki wymagane w danym kroku przewodnika.

Node.js

Każdy krok przewodnika znajduje się w osobnym <step> podfolderze. Każdy krok zawiera:

• Pliki statyczne, takie jak JavaScript, CSS i obrazy, znajdują się w folderze ./<step>/public.
• Routery Express 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ącą prawidłowe uruchomienie aplikacji. Ten katalog zawiera te elementy: + java.com.addons.spring katalog zawiera pliki Application.java i Controller.java. Plik Application.java odpowiada za uruchamianie serwera aplikacji, a plik Controller.java – za obsługę logiki punktu końcowego. + Katalog resources zawiera katalog templates z plikami HTML i JavaScript. Zawiera też plik application.properties określający port do uruchomienia serwera, ś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 zaktualizować plik application.properties o odpowiednią ścieżkę.
  • pom.xml zawiera informacje potrzebne do skompilowania projektu i zdefiniowania 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 pliku .gitignore. W podanym przykładzie jest to secrets/*.p12 (cel magazynu kluczy omówimy w sekcji poniżej). W przypadku przewodnika 2 i nowszych przewodników należy też uwzględnić ścieżkę do pliku client_secret.json, aby nie umieszczać tajnych kluczy w zdalnym repozytorium. W przypadku przewodnika 3 i nowszych przewodników należy dodać ścieżkę do pliku bazy danych H2 i fabryki magazynu danych. Więcej informacji o konfiguracji tych magazynów danych można znaleźć w trzecim przewodniku dotyczącym obsługi powracających użytkowników.
  • mvnw i mvnw.cmd to odpowiednio pliki wykonywalne otoki Maven dla systemów Unix i Windows. Na przykład uruchomienie polecenia ./mvnw --version w systemie Unix spowoduje wyświetlenie m.in. wersji Apache Maven.
  • Katalog .mvn zawiera konfigurację otoki Maven.

Uruchamianie przykładowego serwera

Ważne: aplikację internetową można otworzyć w Google Classroom tylko przez HTTPS. Więcej informacji znajdziesz w sekcji Certyfikat HTTPS.

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

Python

Dane logowania OAuth

Utwórz i pobierz dane logowania OAuth zgodnie z opisem powyżej. Umieść plik JSON w katalogu głównym obok pliku uruchamiającego serwer aplikacji.

Konfigurowanie serwera

Serwer WWW możesz uruchomić na kilka sposobów. Na końcu pliku Pythona dodaj jedną z tych opcji:

1. Niezabezpieczony localhost. Pamiętaj, że ta opcja nadaje się tylko do bezpośredniego testowania w oknie przeglądarki. Niezabezpieczonych domen nie można wczytywać 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. Zabezpieczony localhost. W przypadku argumentu ssl_context musisz podać krotkę plików kluczy SSL.

   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. Ta opcja nadaje się do wdrożenia na serwerze produkcyjnym lub 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

Ostrzeżenie: zanim uruchomisz serwer, musisz skonfigurować projekt Google Cloud, aby uzyskać dostęp do interfejsu Classroom API i wymaganych danych logowania.

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 samodzielny, który będzie używany do uruchamiania aplikacji przez HTTPS. Te dane logowania należy zapisać 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 pęku kluczy systemu operacyjnego.

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

Uruchamianie serwera

Ostrzeżenie: zanim uruchomisz serwer, musisz skonfigurować projekt Google Cloud, aby uzyskać dostęp do interfejsu Classroom API i wymaganych danych logowania.

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

npm run step01

lub

npm run step02

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

Serwer możesz zatrzymać, naciskając Control + C w terminalu.

Java

Konfigurowanie serwera

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

Do lokalnego programowania rozważ użycie narzędzia mkcert. Po zainstalowaniu narzędzia mkcert te polecenia wygenerują lokalnie przechowywany certyfikat do uruchamiania przez HTTPS.

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

Ten przykład zawiera plik magazynu kluczy w katalogu resources. Możesz go przechowywać w dowolnym miejscu, ale pamiętaj, aby zaktualizować plik application.properties o odpowiednią ścieżkę. Nazwa domeny to domena, w której uruchamiasz projekt (np. localhost).

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

Uruchamianie serwera

Ostrzeżenie: zanim uruchomisz serwer, musisz skonfigurować projekt Google Cloud, aby uzyskać dostęp do interfejsu Classroom API i wymaganych danych logowania.

Uruchom serwer, uruchamiają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 i 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 pod adresem https://localhost:5000 lub na porcie określonym w pliku application.properties.