Procedure dettagliate

Questa serie di procedure dettagliate illustra tutte le parti mobili di un componente aggiuntivo di Classroom funzionante. Ogni passaggio della procedura dettagliata affronta concetti specifici e li implementa in un'unica applicazione web. L'obiettivo è aiutarti a impostare, configurare e avviare un componente aggiuntivo funzionale.

Il componente aggiuntivo deve interagire con un progetto Google Cloud. Se non hai dimestichezza con Google Cloud, ti consigliamo di leggere le guide introduttive. Puoi gestire le credenziali, l'accesso API e l'SDK di Google Workspace Marketplace nella console Google Cloud. Per ulteriori informazioni sull'SDK di Marketplace, visita la pagina della guida Google Workspace Marketplace.

Questa guida tratta i seguenti argomenti:

  • Utilizza Google Cloud per creare una pagina da mostrare in un iframe in Classroom.
  • Aggiungi il servizio Single Sign-On (SSO) di Google e consenti agli utenti di accedere.
  • Effettua chiamate API per collegare il componente aggiuntivo a un compito.
  • Soddisfa i principali requisiti di invio dei componenti aggiuntivi e le funzionalità richieste.

Questa guida presuppone che tu abbia familiarità con la programmazione e i concetti fondamentali dello sviluppo web. Ti consigliamo vivamente di leggere la guida alla configurazione del progetto prima di iniziare le procedure dettagliate. Questa pagina contiene importanti dettagli di configurazione che non sono completamente trattati nelle procedure dettagliate.

Esempi di implementazioni

Un esempio di riferimento completo è disponibile in Python. Le implementazioni parziali sono disponibili anche in Java e Node.js. Queste implementazioni sono le origini del codice di esempio che si trovano nelle pagine successive.

Dove eseguire il download

Gli esempi Python e Java sono disponibili nei repository GitHub:

L'esempio di Node.js può essere scaricato come file ZIP:

Prerequisiti

Consulta le sezioni seguenti per preparare un nuovo progetto di componenti aggiuntivi.

Certificato HTTPS

Puoi ospitare la tua app in qualsiasi ambiente di sviluppo, ma il componente aggiuntivo di Classroom è disponibile solo tramite https://. Di conseguenza, hai bisogno di un server con crittografia SSL per eseguire il deployment della tua app o per testarla nell'iframe del componente aggiuntivo.

È possibile utilizzare localhost con un certificato SSL; prendi in considerazione mkcert se devi creare un certificato per lo sviluppo locale.

Progetto Google Cloud

Devi configurare un progetto Google Cloud da utilizzare con questi esempi. Per una panoramica dei passaggi necessari per iniziare, consulta la guida alla creazione di un progetto Google Cloud. La sezione Configura un progetto Google Cloud nella prima procedura dettagliata illustra anche le azioni di configurazione specifiche da eseguire.

Al termine, scarica il tuo ID client OAuth 2.0 come file JSON. Devi aggiungere questo file delle credenziali alla directory di esempio decompressa. Consulta Informazioni sui file per conoscere le località specifiche.

Credenziali OAuth

Per creare nuove credenziali OAuth, segui questi passaggi:

  • Vai alla pagina Credenziali Google Cloud. Assicurati di aver selezionato il progetto corretto nella parte superiore dello schermo.
  • Fai clic su CREA CREDENZIALI e scegli ID client OAuth dal menu a discesa.
  • Nella pagina successiva:
    • Imposta Tipo di applicazione su Applicazione web.
    • In URI di reindirizzamento autorizzati, fai clic su AGGIUNGI URI. Aggiungi il percorso completo per una route di callback per la tua applicazione. Ad esempio, https://my.domain.com/auth-callback o https://localhost:5000/callback. Potrai creare e gestire questa route più avanti in questa procedura dettagliata. Puoi modificare o aggiungere altri percorsi di questo tipo in qualsiasi momento.
    • Fai clic su CREA.
  • Si aprirà una finestra di dialogo con le credenziali appena create. Scegli l'opzione SCARICA JSON. Copia il file JSON scaricato nella directory del server.

Prerequisiti specifici dei linguaggi

Visualizza il file README in ogni repository per l'elenco più aggiornato dei prerequisiti.

Python

Il nostro esempio Python utilizza il framework Flask. Puoi scaricare il codice sorgente completo dai link forniti.

Se necessario, installa Python 3.7 o versioni successive e assicurati che pip sia disponibile.

python3 -m ensurepip --upgrade

Ti consigliamo inoltre di configurare e attivare un nuovo ambiente virtuale Python.

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

In ogni sottodirectory della procedura dettagliata negli esempi scaricati è presente un valore requirements.txt. Puoi installare rapidamente le librerie necessarie utilizzando pip. Utilizza i comandi seguenti per installare le librerie richieste per la prima procedura dettagliata.

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

Node.js

Il nostro esempio di Node.js utilizza il framework Express. Puoi scaricare il codice sorgente completo dai link forniti.

Questo esempio richiede Node.js v16.13 o versioni successive.

Installa i moduli di nodo richiesti utilizzando npm.

npm install

Java

Il nostro esempio Java utilizza il framework Spring Boot. Puoi scaricare il codice sorgente completo dai link forniti.

Installa Java 11+ se non è già installato sulla macchina.

Le applicazioni Spring Boot possono utilizzare Gradle o Maven per gestire le build e le dipendenze. Questo esempio include il wrapper Maven che garantisce una build riuscita senza richiedere l'installazione di Maven.

Nella directory in cui hai scaricato o clonato il progetto, esegui questi comandi per assicurarti di disporre dei prerequisiti per eseguire il progetto.

java --version
./mvnw --version

Su Windows:

java -version
mvnw.cmd --version

Comprendere i file

Le seguenti sezioni descrivono il layout delle directory di esempio.

Nomi directory

Ogni repository contiene diverse directory i cui nomi iniziano con un numero, ad esempio /01-basic-app/. I numeri corrispondono ai passaggi della procedura dettagliata specifici. Ogni directory contiene un'app web completamente funzionale che implementa le funzionalità descritte in una determinata procedura dettagliata. Ad esempio, la directory /01-basic-app/ contiene l'implementazione finale della procedura dettagliata Creare un componente aggiuntivo.

Contenuti della directory

I contenuti della directory variano a seconda del linguaggio di implementazione:

Python

  • La directory root contiene i seguenti file:

    • main.py: il punto di ingresso dell'applicazione Python. Specifica la configurazione del server che vuoi utilizzare in questo file, quindi eseguila per avviare il server.
    • requirements.txt: i moduli Python necessari per eseguire l'app web. Possono essere installati automaticamente utilizzando pip install -r requirements.txt.
    • client_secret.json: il file del client secret scaricato da Google Cloud. Tieni presente che non è incluso nell'archivio di esempio; devi rinominare e copiare il file delle credenziali scaricato nella directory radice di ogni directory.

  • config.py: opzioni di configurazione per il server Flask.

  • La directory webapp include i contenuti dell'applicazione web. Include i seguenti contenuti:

  • La directory /templates/ con i modelli Jinja per varie pagine.

  • La directory /static/ con immagini, CSS e file JavaScript aggiuntivi.

  • routes.py: i metodi dei gestori per le route dell'applicazione web.

  • __init__.py: l'inizializzatore del modulo webapp. Questo inizializzatore avvia il server Flask e carica le opzioni di configurazione impostate in config.py.

  • File aggiuntivi come richiesto da un determinato passaggio della procedura dettagliata.

Node.js

Ogni passaggio della procedura dettagliata può essere trovato nella sottocartella <step> specifica. Ogni passaggio contiene:

  • Si trovano file statici come JavaScript, CSS e immagini nella cartella ./<step>/public.
  • I router Express si trovano nelle cartelle ./<step>/routes.
  • I modelli HTML sono disponibili nelle cartelle ./<step>/views.
  • L'applicazione server è ./<step>/app.js.

Java

La directory del progetto include quanto segue:

  • La directory src.main contiene il codice sorgente e la configurazione per eseguire correttamente l'applicazione. Questa directory include quanto segue: + la directory java.com.addons.spring contiene i file Application.java e Controller.java. Il file Application.java è responsabile dell'esecuzione del server delle applicazioni, mentre il file Controller.java gestisce la logica dell'endpoint. + resources contiene la directory templates con i file HTML e JavaScript. Contiene anche il file application.properties che specifica la porta per eseguire il server, il percorso del file dell'archivio chiavi e il percorso della directory templates. Questo esempio include il file dell'archivio chiavi nella directory resources. Puoi archiviarlo dove preferisci, ma assicurati di aggiornare il file application.properties con il percorso di conseguenza.
    • pom.xml contiene le informazioni necessarie per creare il progetto e definire le dipendenze richieste.
    • .gitignore contiene nomi di file che non devono essere caricati su Git. Assicurati di aggiungere il percorso all'archivio chiavi in questo campo .gitignore. Nell'esempio fornito, questo è secrets/*.p12 (lo scopo dell'archivio chiavi è discusso nella sezione di seguito). Per la procedura dettagliata 2 e oltre, devi includere anche il percorso del file client_secret.json per assicurarti di non includere i tuoi secret in un repository remoto. Per la procedura dettagliata 3 e versioni successive, devi aggiungere il percorso alla fabbrica di datastore e file di database H2. Ulteriori informazioni sulla configurazione di questi datastore sono disponibili nella terza procedura dettagliata sulla gestione delle visite ripetute.
    • mvnw e mvnw.cmd sono gli eseguibili del wrapper Maven, rispettivamente per Unix e Windows. Ad esempio, l'esecuzione di ./mvnw --version su Unix restituisce la versione di Apache Maven, tra le altre informazioni.
    • La directory .mvn contiene la configurazione del wrapper Maven.

Esegui il server di esempio

Devi avviare il server per testarlo. Segui queste istruzioni per eseguire il server di esempio nella lingua che preferisci:

Python

Credenziali OAuth

Crea e scarica le tue credenziali OAuth come descritto in precedenza. Inserisci il file JSON nella directory radice accanto al file di avvio del server dell'applicazione.

Configura il server

Sono disponibili diverse opzioni per l'esecuzione del server web. Alla fine del tuo file Python, aggiungi uno dei seguenti elementi:

  1. localhost non protetto. Tieni presente che questa opzione è adatta solo per eseguire test direttamente in una finestra del browser. I domini non protetti non possono essere caricati nell'iframe del componente aggiuntivo di 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. Proteggi localhost. Devi specificare una tupla di file di chiave SSL per l'argomento 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. È adatto per un deployment server o cloud pronto per la produzione. Ti consigliamo di impostare una variabile di ambiente PORT da utilizzare con questa opzione di avvio.

    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")
    

Avvia il server

Esegui l'applicazione Python per avviare il server come configurato nel passaggio precedente.

python main.py

Fai clic sull'URL visualizzato per visualizzare la tua app web in un browser e verificare che sia in esecuzione correttamente.

Node.js

Configura il server

Per eseguire il server tramite HTTPS, devi creare un auto-certificato da utilizzare per eseguire l'applicazione tramite HTTPS. Queste credenziali devono essere salvate come sslcert/cert.pem e sslcert/key.pem nella cartella principale del repository. Potrebbe essere necessario aggiungere queste chiavi alla catena di chiavi del sistema operativo per consentire al browser di accettarle.

Assicurati che *.pem sia nel file .gitignore perché non vuoi eseguire il commit del file in Git.

Avvia il server

Puoi eseguire l'applicazione con il seguente comando, sostituendo step01 con il passaggio corretto che vuoi eseguire come server (ad esempio, step01 per 01-basic-app e step02 per 02-sign-in).

npm run step01

o un

npm run step02

Viene avviato il server web all'indirizzo https://localhost:5000.

Puoi terminare il server con Control + C nel tuo terminale.

Java

Configura il server

Per eseguire il server tramite HTTPS, devi creare un auto-certificato da utilizzare per eseguire l'applicazione tramite HTTPS.

Potresti usare mkcert per lo sviluppo locale. Dopo aver installato mkcert, i comandi seguenti generano un certificato archiviato localmente da eseguire su HTTPS.

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

Questo esempio include il file dell'archivio chiavi nella directory delle risorse. Puoi archiviarlo dove preferisci, ma assicurati di aggiornare il file application.properties con il percorso di conseguenza. Il nome di dominio è il dominio su cui esegui il progetto (ad esempio, localhost).

Assicurati che *.p12 sia nel file .gitignore perché non vuoi eseguire il commit del file in Git.

Avvia il server

Avvia il server eseguendo il metodo main nel file Application.java. In IntelliJ, ad esempio, puoi fare clic con il tasto destro del mouse su Application.java > Run 'Application' nella directory src/main/java/com/addons/spring o aprire il file Application.java per fare clic sulla freccia verde a sinistra della firma del metodo main(String[] args). In alternativa, puoi eseguire il progetto in una finestra del terminale:

./mvnw spring-boot:run

o su Windows:

mvnw.cmd spring-boot:run

Il server viene avviato all'indirizzo https://localhost:5000 o alla porta specificata in application.properties.