Ta seria przewodników ilustruje ruchome części działającego dodatku do Classroom. Każdy przewodnik dotyczy konkretnych koncepcji i implementuje je w jednej aplikacji internetowej. Chcemy pomóc Ci skonfigurować i uruchomić funkcjonalny dodatek.
Dodatek musi współdziałać z projektem Google Cloud. Jeśli nie znasz Google Cloud, zalecamy przeczytanie przewodników dla początkujących. Dane logowania, dostęp do interfejsu API oraz pakiet SDK Google Workspace Marketplace możesz zarządzać w konsoli Google Cloud. Więcej informacji o pakiecie SDK Marketplace znajdziesz na stronie przewodnika po umieszczaniu informacji w Google Workspace Marketplace.
W tym przewodniku omówiono następujące tematy:
- Użyj Google Cloud, aby utworzyć stronę do wyświetlania 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 spełnij w nich wymagane funkcje.
W tym przewodniku zakładamy, że masz już wiedzę na temat programowania i podstawowych pojęć związanych z tworzeniem stron internetowych. Zdecydowanie zalecamy, aby przed rozpoczęciem przewodników zapoznać się z przewodnikiem po konfiguracji projektu. Ta strona zawiera ważne szczegóły konfiguracji, które nie zostały w pełni omówione w instrukcjach.
Przykładowe implementacje
Pełny przykład odwołania jest dostępny w języku Python. Częściowe implementacje są też dostępne w językach Java i Node.js. Te implementacje stanowią źródła przykładowego kodu, które można znaleźć na kolejnych stronach.
Skąd pobrać
Przykłady Pythona i Javy są dostępne w repozytoriach GitHub:
Próbkę środowiska Node.js możesz pobrać jako plik ZIP:
Wymagania wstępne
Zapoznaj się z poniższymi sekcjami, aby przygotować nowy projekt dodatków.
Certyfikat HTTPS
Możesz hostować aplikację w dowolnym środowisku programistycznym, ale dodatek do Classroom jest dostępny tylko w domenie https://
. Dlatego do wdrożenia aplikacji lub przetestowania jej w dodatkowym elemencie iframe potrzebujesz serwera z szyfrowaniem SSL.
Możesz używać localhost
z certyfikatem SSL. Jeśli chcesz utworzyć certyfikat na potrzeby lokalnego programowania, rozważ użycie mkcert.
Projekt Google Cloud
Aby wykorzystać te przykłady, musisz skonfigurować projekt Google Cloud. Zapoznaj się z przewodnikiem tworzenia projektów w Google Cloud, w którym znajdziesz omówienie czynności niezbędnych do rozpoczęcia pracy. Sekcja Skonfiguruj projekt Google Cloud w pierwszym przewodniku zawiera też instrukcje poszczególnych działań związanych z konfiguracją, które należy wykonać.
Gdy skończysz, pobierz identyfikator klienta OAuth 2.0 jako plik JSON. Musisz dodać ten plik danych logowania do rozpakowanego przykładowego katalogu. Informacje o konkretnych lokalizacjach znajdziesz w artykule Omówienie plików.
Dane logowania OAuth
Aby utworzyć nowe dane logowania OAuth, wykonaj te czynności:
- Otwórz stronę Google Cloud Credentials (Dane logowania do Google Cloud). Sprawdź, czy u góry ekranu masz wybrany właściwy projekt.
- Kliknij UTWÓRZ DANE uwierzytelniające i z 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 aplikacji. Na przykład:
https://my.domain.com/auth-callback
lubhttps://localhost:5000/callback
. Możesz utworzyć i obsługiwać tę trasę w dalszej części tego przewodnika. W każdej chwili możesz edytować lub dodać więcej takich tras. - Kliknij UTWÓRZ.
- Pojawi się okno z nowo utworzonymi danymi logowania. Wybierz opcję POBIERZ JSON. Skopiuj pobrany plik JSON do katalogu serwera.
Wymagania wstępne dla różnych języków
Najbardziej aktualną 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ć spod tych 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 środowiska wirtualnego Pythona.
python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate
Pobrany przykładowy podkatalog przewodnika zawiera element requirements.txt
. Wymagane biblioteki możesz szybko zainstalować za pomocą pip
. Za pomocą tych poleceń zainstaluj wymagane biblioteki na potrzeby pierwszego przewodnika.
cd flask/01-basic-app
pip install -r requirements.txt
Node.js
W naszym przykładzie ze środowiskiem Node.js korzystamy z platformy Express. Pełny kod źródłowy możesz pobrać, korzystając z udostępnianych linków.
Ten przykład wymaga środowiska Node.js 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. Pełny kod źródłowy możesz pobrać, korzystając z udostępnianych linków.
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 zależnościami. Ten przykład zawiera kod Maven, który zapewnia pomyślną kompilację bez konieczności instalowania samego narzędzia Maven.
W katalogu, w którym projekt został pobrany lub sklonowany, uruchom te polecenia, aby mieć pewność, że spełniasz wymagania wstępne do uruchomienia projektu.
java --version
./mvnw --version
Lub w systemie Windows:
java -version
mvnw.cmd --version
Informacje o plikach
W kolejnych sekcjach opisano układ przykładowych katalogów.
Nazwy katalogów
Każde repozytorium zawiera kilka katalogów, których nazwy zaczynają się od liczby, np. /01-basic-app/
. Liczby odpowiadają poszczególnym krokom przewodnika.
Każdy katalog zawiera w pełni funkcjonalną aplikację internetową, która implementuje funkcje opisane w konkretnym przewodniku. Na przykład w katalogu /01-basic-app/
znajduje się końcowa implementacja instrukcji tworzenia dodatku.
Zawartość katalogu
Zawartość katalogu różni się w zależności od języka implementacji:
Python
Katalog główny zawiera następujące pliki:
main.py
– punkt wejścia aplikacji w języku Python. Określ konfigurację serwera, której chcesz użyć w tym pliku, a następnie uruchom ją, aby uruchomić serwer.requirements.txt
– moduły Pythona wymagane do uruchomienia aplikacji internetowej. Można je instalować automatycznie za pomocąpip install -r requirements.txt
.client_secret.json
– plik z kluczem klienta pobrany z Google Cloud. Pamiętaj, że nie ma go w przykładowym archiwum. Musisz zmienić nazwę pobranego pliku danych logowania i skopiować je do każdego katalogu głównego katalogu.
config.py
– opcje konfiguracji serwera Flask.Katalog
webapp
zawiera treść aplikacji internetowej. Oto niektóre z nich: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 internetowych.__init__.py
– inicjator modułuwebapp
. Ten inicjator uruchamia serwer Flask i wczytuje opcje konfiguracji ustawione wconfig.py
.Dodatkowe pliki wymagane w przypadku konkretnego kroku przewodnika.
Node.js
Każdy krok przejścia można znaleźć w osobnym podfolderze <step>
. Każdy krok obejmuje:
- 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:
- Katalog
src.main
zawiera kod źródłowy i konfigurację potrzebne do prawidłowego uruchomienia aplikacji. Ten katalog zawiera następujące elementy: +java.com.addons.spring
. Zawiera plikiApplication.java
iController.java
. PlikApplication.java
odpowiada za uruchamianie serwera aplikacji, a plikController.java
odpowiada za logikę punktu końcowego. Katalog +resources
zawiera katalogtemplates
z plikami HTML i JavaScript. Zawiera on również plikapplication.properties
określający port, na którym zostanie uruchomiony serwer, ścieżkę do pliku magazynu kluczy oraz ścieżkę do katalogutemplates
. Ten przykład obejmuje plik magazynu kluczy znajdujący się w kataloguresources
. Możesz go przechowywać w dowolnym miejscu, ale pamiętaj, by zaktualizować plikapplication.properties
z odpowiednią ścieżką.pom.xml
zawiera informacje potrzebne do utworzenia projektu i zdefiniowania wymaganych zależności..gitignore
zawiera nazwy plików, których nie należy przesyłać do git. Pamiętaj, aby dodać ścieżkę do magazynu kluczy w tym.gitignore
. W podanym przykładzie ma to wartośćsecrets/*.p12
(cel magazynu kluczy został omówiony w sekcji poniżej). W przypadku przewodnika 2 i drugich musisz też podać ścieżkę do plikuclient_secret.json
, aby mieć pewność, że obiekty tajne nie zostaną umieszczone w zdalnym repozytorium. W przypadku przewodnika 3 i nowszych musisz dodać ścieżkę do pliku bazy danych H2 i fabryki pliku datastore. Więcej informacji o konfigurowaniu tych magazynów danych znajdziesz w trzecim przewodniku po obsłudze powtarzających się wizyt.mvnw
imvnw.cmd
to pliki wykonywalne kodu Maven dla systemów Unix i Windows. Na przykład uruchomienie polecenia./mvnw --version
w systemie Unix powoduje wygenerowanie m.in. wersji Apache Maven.- Katalog
.mvn
zawiera konfigurację kodu Maven.
Uruchamianie przykładowego serwera
Aby przetestować serwer, musisz go uruchomić. Wykonaj te instrukcje, aby uruchomić przykładowy serwer w wybranym języku:
Python
Dane logowania OAuth
Utwórz i pobierz dane logowania OAuth w sposób opisany powyżej. Umieść plik JSON w katalogu głównym obok pliku uruchamiania serwera aplikacji.
Konfigurowanie serwera
Serwer WWW możesz uruchomić na kilka sposobów. Na końcu pliku Pythona dodaj jeden z tych elementów:
Niezabezpieczony plik
localhost
. Pamiętaj, że jest to odpowiednie do bezpośredniego testowania w oknie przeglądarki. Niezabezpieczonych domen nie można wczytywać w elemencie iframe dodatku 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)
Zabezpiecz urządzenie
localhost
. W argumenciessl_context
musisz określić 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)
Serwer Gunicorn Jest to odpowiednie rozwiązanie w przypadku serwera produkcyjnego 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 zgodnie z konfiguracją w poprzednim kroku.
python main.py
Kliknij wyświetlony adres URL, aby otworzyć aplikację internetową w przeglądarce i sprawdzić, czy działa poprawnie.
Node.js
Konfigurowanie serwera
Jeśli chcesz używać serwera z protokołem HTTPS, musisz utworzyć własny certyfikat, który posłuży do uruchamiania aplikacji przez HTTPS. Te dane logowania powinny być zapisane jako sslcert/cert.pem
i sslcert/key.pem
w folderze głównym repozytorium. Konieczne może być dodanie tych kluczy do łańcucha kluczy systemu operacyjnego, aby przeglądarka mogła je zaakceptować.
Sprawdź, czy *.pem
znajduje się w pliku .gitignore
, bo nie chcesz zatwierdzać pliku na Git.
Uruchamianie serwera
Możesz uruchomić aplikację, korzystając z tego polecenia, zamieniając step01
na prawidłowy krok, który ma zostać uruchomiony jako serwer (na przykład 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 Control + C
w terminalu.
Java
Konfigurowanie serwera
Jeśli chcesz używać serwera z protokołem HTTPS, musisz utworzyć własny certyfikat, który posłuży do uruchamiania aplikacji przez HTTPS.
Do programowania lokalnego warto używać narzędzia mkcert. Po zainstalowaniu mkcert
podane niżej polecenia generują lokalnie przechowywany certyfikat uruchamiany przez HTTPS.
mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>
W tym przykładzie umieszczamy plik magazynu kluczy w katalogu zasobów. Możesz go przechowywać w dowolnym miejscu, ale pamiętaj, aby zaktualizować plik application.properties
z odpowiednią ścieżką. Nazwa domeny to domena, w której uruchamiasz projekt (np. localhost
).
Sprawdź, czy *.p12
znajduje się w pliku .gitignore
, bo nie chcesz zatwierdzać pliku na Git.
Uruchamianie serwera
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 podpisu 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 stronie https://localhost:5000
lub na porcie określonym w application.properties
.