Przewodniki

Ta seria przewodników ilustruje wszystkie ruchome części działającego dodatku do Classroom. Każdy z kroków zawiera omówienie konkretnych koncepcji i zaimplementowania ich w pojedynczej aplikacji internetowej. Ma ona pomóc Ci w konfigurowaniu i wdrażaniu funkcjonalnego dodatku.

Dodatek musi wchodzić w interakcję z projektem Google Cloud. Jeśli nie znasz Google Cloud, zalecamy przeczytanie przewodników dla początkujących. Dane logowania, dostęp do interfejsów API i pakiet GWM SDK zarządzasz w konsoli Google Cloud. Więcej informacji o pakiecie GWM SDK znajdziesz na stronie przewodnika z informacjami o Google Workspace Marketplace.

Tematy w tym przewodniku:

• Użyj Google Cloud, aby utworzyć stronę wyświetlaną w elemencie iframe w Classroom.
• Dodaj logowanie jednokrotne przez Google i zezwól użytkownikom na logowanie się.
• Wywołuj interfejs API, aby dołączyć dodatek do projektu.
• Spełnij najważniejsze wymagania dotyczące przesyłania dodatków i ich wymagane funkcje.

W tym przewodniku zakładamy, że znasz już programowanie i podstawowe pojęcia związane z tworzeniem stron internetowych. Przed rozpoczęciem korzystania z tych instrukcji zdecydowanie zalecamy zapoznanie 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 tych instrukcjach.

Przykładowe implementacje

Pełne przykłady materiałów referencyjnych znajdziesz w językach JavaScript, Python i Java. Te implementacje są źródłami przykładowego kodu występującego na kolejnych stronach.

Skąd pobrać

Pełne archiwa naszych przykładów można pobrać, klikając poniższe linki.

• Archiwum Pythona
• Archiwum Node.js
• Archiwum Java

Wymagania wstępne

Zapoznaj się z sekcjami poniżej, aby przygotować nowy projekt dodatków.

Certyfikat HTTPS

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

można używać localhost z certyfikatem SSL; rozważ użycie mkcert, jeśli chcesz utworzyć certyfikat do programowania lokalnego.

Projekt Google Cloud

Aby używać tych przykładów, musisz skonfigurować projekt Google Cloud. Opis czynności niezbędnych do rozpoczęcia znajdziesz w przewodniku po tworzeniu projektu Google Cloud. Sekcja Konfigurowanie projektu Google Cloud w pierwszym przewodniku zawiera też omówienie konkretnych działań konfiguracyjnych, które należy wykonać.

Gdy skończysz, pobierz identyfikator klienta OAuth 2.0 jako plik JSON. Ten plik danych logowania musisz dodać do rozpakowanego przykładowego katalogu. Informacje o konkretnych lokalizacjach znajdziesz w sekcji Informacje o plikach.

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. Sprawdź, czy na górze ekranu jest wybrany właściwy projekt.
• Kliknij UTWÓRZ DANE LOGOWANIA i wybierz z menu 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ę trasy wywołania zwrotnego aplikacji. np. https://my.domain.com/auth-callback lub https://localhost:5000/callback. Tę trasę utworzysz i obsługujesz w dalszej części tego przewodnika. W każdej chwili możesz edytować lub dodać więcej takich tras.
  • Kliknij UTWÓRZ.
• Zostanie wyświetlone okno dialogowe z nowo utworzonymi danymi logowania. Wybierz opcję POBIERZ JSON. Skopiuj pobrany plik .json do katalogu serwera.

Wymagania wstępne związane z różnymi językami

Najbardziej aktualną listę wymagań wstępnych znajdziesz w pliku README w każdym archiwum.

Python

W naszym przykładzie w Pythonie użyto platformy Flask. Pełny kod źródłowy można pobrać, klikając link powyżej.

W razie potrzeby zainstaluj Python 3.7 lub nowszy i sprawdź, czy dostępny jest język 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 pobranych przykładach w każdym podkatalogu przewodnika znajduje się requirements.txt. Wymagane biblioteki możesz szybko zainstalować za pomocą pip. Użyj poniższych poleceń, aby zainstalować biblioteki wymagane w pierwszym przewodniku.

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

Node.js

W naszym przykładzie Node.js korzystamy z platformy Express. Pełny kod źródłowy można pobrać, klikając link powyżej.

Ten przykład wymaga środowiska Node.js w wersji 16.13 lub nowszej.

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

npm install

Java

Nasz przykład w Javie korzysta z platformy Spring Boot. Pełny kod źródłowy można pobrać, klikając link powyżej.

Zainstaluj Java 11+, jeśli jeszcze nie masz tej wersji 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 udaną kompilację bez konieczności instalowania samej aplikacji Maven.

W katalogu, w którym pobrano lub sklonowano projekt, uruchom następujące polecenia, aby sprawdzić, czy spełniasz wymagania wstępne do uruchomienia projektu.

java --version
./mvnw --version

Lub w systemie Windows:

java -version
mvnw.cmd --version

Omówienie plików

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

Nazwy katalogów

Każde archiwum zawiera kilka katalogów, których nazwy zaczynają się od cyfry, np. /01-basic-app/. Liczby odpowiadają określonym krokom przewodnika. Każdy katalog zawiera w pełni funkcjonalną aplikację internetową, która implementuje funkcje opisane w konkretnym przewodniku. np. 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

• Główny katalog zawiera te 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 tajnego klienta pobrany z Google Cloud. Zwróć uwagę, że nie ma go w przykładowym archiwum. Zmień nazwę pobranego pliku danych logowania i skopiuj go do każdego katalogu głównego.

    Ważne: aby uruchomić przykłady, musisz podać plik tajnego klucza klienta z swojego projektu Google Cloud.

• config.py – opcje konfiguracji serwera Flask.

• Katalog webapp zawiera zawartość aplikacji internetowej. Obejmują one:

• 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łu webapp. Ten inicjator uruchamia serwer Flask i wczytuje opcje konfiguracji ustawione w config.py.

• Dodatkowe pliki zgodnie z wymaganiami konkretnego kroku przewodnika.

Node.js

Każdy krok przewodnika można znaleźć w jego własnym 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 te elementy:

• Katalog src.main zawiera kod źródłowy i konfigurację niezbędne do uruchomienia aplikacji. W tym katalogu: + java.com.addons.spring zawiera pliki Application.java i Controller.java. Plik Application.java odpowiada za uruchomienie serwera aplikacji, a plik Controller.java obsługuje logikę punktu końcowego. + resources zawiera katalog templates z plikami HTML i JavaScript. Zawiera on też plik application.properties, który określa port, na którym uruchomiono serwer, ścieżkę do pliku magazynu kluczy i ścieżkę do katalogu templates. W tym przykładzie plik magazynu kluczy znajduje się w katalogu resources. Możesz ją przechowywać, gdziekolwiek chcesz, ale pamiętaj, by zaktualizować plik application.properties, podając 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 w elemencie .gitignore dodać ścieżkę do magazynu kluczy. W podanym przykładzie jest to secrets/*.p12 (cel magazynu kluczy został omówiony w sekcji poniżej). W instrukcji 2, a potem poza nią, musisz też podać ścieżkę do pliku client_secret.json, aby mieć pewność, że nie umieścisz swoich obiektów tajnych w zdalnym repozytorium. W przypadku instrukcji 3 i kolejnych należy dodać ścieżkę do pliku bazy danych H2 i fabryki magazynu danych plików. Więcej informacji o konfigurowaniu tych magazynów danych znajdziesz w trzecim przewodniku na temat obsługi ponownych wizyt.
  • mvnw i mvnw.cmd to pliki wykonywalne opakowań Maven dla systemu Unix i Windows. Na przykład uruchomienie polecenia ./mvnw --version w systemie uniksowym powoduje m.in. wyświetlenie wersji Apache Maven.
  • Katalog .mvn zawiera konfigurację otoki Maven.

Uruchamianie serwera przykładowego

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

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 startowego serwera aplikacji.

Konfigurowanie serwera

Serwer WWW możesz uruchomić na kilka sposobów. Na końcu pliku w Pythonie dodaj:

1. Niezabezpieczony: localhost. Pamiętaj, że jest to rozwiązanie do bezpośredniego testowania tylko 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. Zabezpiecz urządzenie localhost. Musisz określić kropkę plików klucza 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. Gunicorn. Jest to odpowiednie w przypadku serwera gotowego do produkcji 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

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 zgodnie z konfiguracją uzyskaną w poprzednim kroku.

python main.py

Kliknij adres URL, aby otworzyć aplikację internetową w przeglądarce i sprawdzić, czy działa ona prawidłowo.

Node.js

Konfigurowanie serwera

Aby serwer mógł używać protokołu HTTPS, musisz utworzyć własny certyfikat, który będzie używany do uruchamiania aplikacji przez HTTPS. Dane logowania należy zapisać jako sslcert/cert.pem i sslcert/key.pem w głównym folderze repozytorium. Być może musisz dodać te klucze do łańcucha kluczy systemu operacyjnego, aby przeglądarka je akceptowała.

Sprawdź, czy plik *.pem znajduje się w pliku .gitignore, bo nie chcesz ustawiać go na git.

Uruchamianie serwera

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

Możesz uruchomić aplikację za pomocą poniższego polecenia, zastępując step01 odpowiednim krokiem, który chcesz uruchomić jako serwer (np. step01 dla aplikacji 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 zamknąć serwer, używając w terminalu Control + C.

Java

Konfigurowanie serwera

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

Rozważ użycie mkcert na potrzeby programowania lokalnego. Po zainstalowaniu mkcert poniższe polecenia generują 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 został umieszczony w katalogu zasobów. Możesz ją przechowywać, gdziekolwiek chcesz, ale pamiętaj, aby zaktualizować plik application.properties, podając odpowiednią ścieżkę. Nazwa domeny to domena, w której uruchamiasz projekt (na przykład localhost).

Sprawdź, czy plik *.p12 znajduje się w pliku .gitignore, bo nie chcesz ustawiać go na git.

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 narzędziu 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 pod adresem https://localhost:5000 lub na porcie określonym w application.properties.