Przewodniki

Ta seria instrukcji ilustruje ruchome części mechanizmu Dodatek do Classroom. Każdy krok prezentacji dotyczy konkretnych i wdrażania ich w jednej aplikacji internetowej. Chcemy Ci pomóc podczas konfigurowania, konfigurowania i uruchamiania funkcjonalnego dodatku.

Dodatek musi współdziałać z projektem Google Cloud. Jeśli nie znasz funkcji Google Cloud, zalecamy przeczytanie przewodników dla początkujących. Ty zarządzasz dane logowania, dostęp do interfejsu API i pakietu SDK Google Workspace Marketplace konsoli Google Cloud. Więcej informacji na temat pakiet SDK Marketplace znajdziesz w Google Workspace Marketplace. strony przewodnika.

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 umiesz programować i poruszać się po stronach internetowych koncepcjach rozwoju. Zdecydowanie zalecamy zapoznanie się z sekcją Konfiguracja projektu . Ta strona zawiera ważne szczegóły konfiguracji, które nie zostały w pełni opisane 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. Takie implementacje są przykładowego kodu znalezionego na kolejnych stronach.

Skąd pobrać

Przykłady Pythona i Javy są dostępne w repozytoriach GitHub:

• Repozytorium Pythona

• Repozytorium Java

Próbkę środowiska Node.js możesz pobrać jako plik ZIP:

• Archiwum Node.js

Wymagania wstępne

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

Certyfikat HTTPS

Aplikację można hostować w dowolnym środowisku programistycznym, jednak Dodatek do Classroom jest dostępny tylko do https://. Dlatego potrzebujesz serwera z szyfrowaniem SSL, aby wdrożyć aplikację lub ją przetestować w elemencie iframe dodatku.

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

Projekt Google Cloud

Aby wykorzystać te przykłady, musisz skonfigurować projekt Google Cloud. Zobacz Przewodnik po tworzeniu projektów Google Cloud, w którym omówione są niezbędne aby rozpocząć pracę. Konfigurowanie projektu Google Cloud W pierwszym przewodniku przedstawiliśmy też konkretną konfigurację. działań, jakie warto podjąć.

Gdy skończysz, pobierz identyfikator klienta OAuth 2.0 jako plik JSON. Musisz dodać ten plik danych logowania do rozpakowanego przykładowego katalogu. Przeczytaj sekcję Omówienie w konkretnych lokalizacjach.

Dane logowania OAuth

Ważne: Twoja aplikacja internetowa musi korzystać z danych logowania OAuth 2.0 zarządzanych w Google Chmura.

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

• Otwórz stronę Google Cloud Credentials (Dane logowania do Google Cloud). Sprawdź, czy właściwy projekt wybrany u góry ekranu.
• Kliknij UTWÓRZ DANE LOGOWANIA i 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łny ścieżki wywołania zwrotnego aplikacji. Przykład: https://my.domain.com/auth-callback lub https://localhost:5000/callback Tworzysz tę trasę i obsługujesz ją 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 Opcja POBIERZ plik JSON. Skopiuj pobrany plik JSON na serwer katalogu.

Wymagania wstępne dla różnych języków

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

Python

Nasz przykład w Pythonie korzysta z platformy Flask. Możesz pobrać by uzyskać pełny kod źródłowy w linkach.

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 serwera w Pythonie. dla środowiska.

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

W każdym podkatalogu przewodnika znajduje się element requirements.txt pobrane przykłady. Wymagane biblioteki możesz szybko zainstalować za pomocą pip Za pomocą tych poleceń zainstaluj wymagane biblioteki oto pierwszy przewodnik.

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, jaki znajdziesz w linkach.

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. Możesz pobrać pełny kod źródłowy, jaki znajdziesz w linkach.

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.

W katalogu, w którym został pobrany lub sklonowany projekt, uruchom te polecenia, aby upewnić się, ż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 cyfry, na przykład /01-basic-app/. Liczby odpowiadają poszczególnym krokom przewodnika. Każdy katalog zawiera w pełni funkcjonalną aplikację internetową, w której zaimplementowano funkcje: opisane w konkretnym przewodniku. Na przykład /01-basic-app/ w katalogu znajduje się końcowa implementacja elementu Create an add-on (Utwórz dodatek) .

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. Podaj serwer konfiguracji, której chcesz użyć w tym pliku, a następnie uruchom go uruchom serwer.
  • requirements.txt – moduły Pythona wymagane do uruchomienia aplikacji internetowej. Mogą być one instalowane automatycznie za pomocą aplikacji pip install -r requirements.txt.

  • client_secret.json – plik z tajnym kluczem klienta pobrany z Google. Google Cloud. Pamiętaj, że nie ma tego w przykładowym archiwum. Ty zmień nazwę pobranego pliku danych logowania i skopiuj go katalog główny.

    Ważne: musisz podać plik tajnego klucza klienta ze swojego projektu Google Cloud.

• 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 pomocniczym kodem JavaScript .

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

• __init__.py – inicjator modułu webapp. Ten Inicjator uruchamia serwer Flask i wczytuje opcje konfiguracji. ustawiono w komórce config.py.

• Dodatkowe pliki wymagane w przypadku konkretnego kroku przewodnika.

Node.js

Każdy krok przejścia można znaleźć w oddzielnym <step> folderu głównego. Każdy krok obejmuje:

• Pliki statyczne, takie jak JavaScript, CSS i obrazy, znajdują się Folder ./<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ę do uruchomienia aplikacji. Ten katalog zawiera następujące elementy: + java.com.addons.spring Katalog zawiera Application.java i Controller.java pliki. Plik Application.java odpowiada za uruchomienie serwera aplikacji, podczas gdy plik Controller.java obsługuje i punktu końcowego. + resources zawiera katalog templates z Pliki HTML i JavaScript. Zawiera również Plik application.properties określający port, na którym zostanie uruchomione serwera, ścieżkę do pliku magazynu kluczy i ścieżkę do klucza templates. Ten przykład zawiera plik magazynu kluczy w katalogu resources. Możesz ją zapisać w dowolnym miejscu ale pamiętaj o zaktualizowaniu usługi application.properties ze ścieżką.
  • pom.xml zawiera informacje potrzebne do skompilowania projektu oraz zdefiniować wymagane 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 jest to secrets/*.p12 (cel parametru omówiono w sekcji poniżej). Przewodnik 2 i należy też podać ścieżkę do pliku client_secret.json, aby mieć pewność, że nie uwzględnisz swoich w repozytorium zdalnym. W przewodniku 3 i kolejnych należy dodać ścieżkę do pliku bazy danych H2 i pliku datastore fabryki. Więcej informacji o konfiguracji tych magazynów danych: można znaleźć w trzecim przewodniku po obsłudze powtarzających się wizyt.
  • mvnw i mvnw.cmd to pliki wykonywalne kodu Maven dla Unix i Windows. Na przykład uruchomienie ./mvnw --version na System Unix na wyjściu generuje m.in. wersję Apache Maven.
  • Katalog .mvn zawiera konfigurację kodu Maven.

Uruchamianie przykładowego serwera

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

Aby przetestować serwer, musisz go uruchomić. Wykonaj te instrukcje, aby uruchom przykładowy serwer w wybranym języku:

Python

Dane logowania OAuth

Utwórz i pobierz dane logowania OAuth w sposób opisany powyżej. Miejsce plik JSON w katalogu głównym obok serwera aplikacji uruchom plik.

Konfigurowanie serwera

Serwer WWW możesz uruchomić na kilka sposobów. Na koniec Pythona, dodaj jeden z tych elementów:

1. Niezabezpieczony plik localhost. Nadaje się to do bezpośredniego testowania tylko w oknie przeglądarki; niezabezpieczonych domen nie można wczytać Element 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)
   

2. Zabezpiecz urządzenie localhost. Musisz określić krotkę plików kluczy SSL dla ssl_context argument.

   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 dla serwera produkcyjnego lub wdrożenie w chmurze. Zalecamy ustawienie zmiennej środowiskowej PORT dla użyj 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: przed uruchomieniem serwera musisz skonfigurować projektu Google Cloud, aby uzyskać dostęp do Interfejs API Classroom i wymagane dane logowania.

Uruchom aplikację w Pythonie, aby uruchomić serwer zgodnie z konfiguracją poprzedniego kroku.

python main.py

Kliknij wyświetlony adres URL, aby otworzyć aplikację internetową w przeglądarce i potwierdzić, ale działa prawidłowo.

Node.js

Konfigurowanie serwera

Aby serwer działał przy użyciu protokołu HTTPS, musisz utworzyć własny certyfikat która służy do uruchamiania aplikacji przez HTTPS. Dane logowania powinny być zapisano jako sslcert/cert.pem i sslcert/key.pem w katalogu głównym repozytorium folderu Dysku. Konieczne może być dodanie tych kluczy do łańcucha kluczy systemu operacyjnego, aby przeglądarki, aby je zaakceptować.

Sprawdź, czy *.pem znajduje się w pliku .gitignore, bo nie chcesz aby przekazać plik do Git.

Uruchamianie serwera

Ostrzeżenie: przed uruchomieniem serwera musisz skonfigurować projektu Google Cloud, aby uzyskać dostęp do Interfejs API Classroom i wymagane dane logowania.

Możesz uruchomić tę aplikację, używając tego polecenia, podstawiając za step01 dla odpowiedniego kroku, który chcesz uruchomić jako serwer (na przykład step01 w przypadku aplikacji 01-basic-app i step02 w przypadku logowania się 02).

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

Aby serwer działał przy użyciu protokołu HTTPS, musisz utworzyć własny certyfikat która służy do uruchamiania aplikacji przez HTTPS.

Do programowania lokalnego warto używać narzędzia mkcert. Po zainstalowaniu aplikacji mkcert następujące polecenia wygenerują lokalnie przechowywany certyfikat do uruchomienia 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 możesz przechowywać dane w dowolnym miejscu, ale pamiętaj, aby zawsze 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 aby przekazać plik do Git.

Uruchamianie serwera

Ostrzeżenie: przed uruchomieniem serwera musisz skonfigurować projektu Google Cloud, aby uzyskać dostęp do Interfejs API Classroom i wymagane dane logowania.

Uruchom serwer, uruchamiając metodę main w narzędziu Application.java . Na przykład w IntelliJ możesz kliknąć prawym przyciskiem myszy Application.java Run 'Application' w src/main/java/com/addons/spring lub otwórz aplikację Application.java aby kliknąć zieloną strzałkę po lewej stronie ikony main(String[] args) podpis metody. Możesz też uruchomić projekt w terminalu okno:

./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ślono w kolumnie application.properties.