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, implementandoli in un'unica applicazione web. L'obiettivo è aiutarti a impostare, configurare e avviare un componente aggiuntivo funzionante.
Il componente aggiuntivo deve interagire con un progetto Google Cloud. Se non hai dimestichezza con Google Cloud, ti consigliamo di leggere la Guida introduttiva. Puoi gestire le credenziali, l'accesso API e l'SDK GWM nella console Google Cloud. Per saperne di più sull'SDK GWM, visita la pagina della guida relativa alla scheda di 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 requisiti principali per l'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 trattati completamente nelle procedure dettagliate.
Esempi di implementazioni
Esempi di riferimento completi sono disponibili in JavaScript, Python e Java. Queste implementazioni sono le origini del codice di esempio presente nelle pagine successive.
Dove scaricare
Gli archivi completi dei nostri esempi possono essere scaricati utilizzando i link di seguito.
Prerequisiti
Esamina le seguenti sezioni 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://
. Pertanto,
devi avere 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. Considera mkcert se devi creare un certificato per lo sviluppo locale.
Progetto Google Cloud
Devi configurare un progetto Google Cloud da utilizzare con questi esempi. Consulta la guida alla creazione di progetti Google Cloud per una panoramica dei passaggi necessari per iniziare. La sezione Configurare un progetto Google Cloud nella prima procedura dettagliata illustra anche le azioni di configurazione specifiche da intraprendere.
Al termine, scarica il tuo ID client OAuth 2.0 come file JSON. Devi aggiungere questo file di credenziali alla directory di esempio decompressa. Consulta Interpretazione dei file per sedi specifiche.
Credenziali OAuth
Per creare nuove credenziali OAuth:
- 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 di un percorso di callback per la tua applicazione. Ad esempio,
https://my.domain.com/auth-callback
ohttps://localhost:5000/callback
. Potrai creare e gestire questa route più avanti in questa procedura dettagliata. Puoi modificare questi percorsi o aggiungerne altri in qualsiasi momento. - Fai clic su CREA.
- Viene visualizzata 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 per lingua
Visualizza il file README in ogni archivio per visualizzare l'elenco più aggiornato dei prerequisiti.
Python
Il nostro esempio Python utilizza il framework Flask. Puoi scaricare il codice sorgente completo dal link precedente.
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
Negli esempi scaricati, è presente un requirements.txt
in ogni sottodirectory della procedura dettagliata. Puoi installare rapidamente le librerie richieste 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 Node.js utilizza il framework Express. Puoi scaricare il codice sorgente completo dal link precedente.
Questo esempio richiede Node.js v16.13 o versioni successive.
Installa i moduli dei nodi richiesti utilizzando npm
.
npm install
Java
Il nostro esempio Java utilizza il framework Spring Boot. Puoi scaricare il codice sorgente completo dal link precedente.
Installa Java 11 o versioni successive se non l'hai già installato sulla tua 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 i comandi seguenti per assicurarti di disporre dei prerequisiti per eseguire il progetto.
java --version
./mvnw --version
Oppure su Windows:
java -version
mvnw.cmd --version
Comprendere i file
Le seguenti sezioni descrivono il layout delle directory di esempio.
Nomi delle directory
Ogni archivio contiene diverse directory i cui nomi iniziano con un numero, ad esempio /01-basic-app/
. I numeri corrispondono a passaggi specifici della procedura dettagliata. 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 in base alla lingua 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 utilizzandopip 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 in ogni directory principale.
config.py
: opzioni di configurazione per il server Flask.La directory
webapp
contiene i contenuti dell'applicazione web. Include i seguenti contenuti:La directory
/templates/
con modelli Jinja per varie pagine.La directory
/static/
con immagini, file CSS e file JavaScript accessori.routes.py
: i metodi di gestore per le route delle applicazioni web.__init__.py
: l'inizializzazione per il modulowebapp
. Questo inizializzatore avvia il server Flask e carica le opzioni di configurazione impostate inconfig.py
.File aggiuntivi richiesti da un determinato passaggio della procedura dettagliata.
Node.js
Ogni passaggio del walkthough è disponibile nella rispettiva sottocartella <step>
. Ogni passaggio contiene:
- I file statici come JavaScript, CSS e immagini si trovano nella cartella
./<step>/public
. - I router Express si trovano nelle cartelle
./<step>/routes
. - I modelli HTML si trovano 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: +java.com.addons.spring
contiene i fileApplication.java
eController.java
. Il fileApplication.java
è responsabile dell'esecuzione dell'application server, mentre il fileController.java
gestisce la logica dell'endpoint. + La directoryresources
contiene la directorytemplates
con file HTML e JavaScript. Contiene inoltre il fileapplication.properties
che specifica la porta per l'esecuzione del server, il percorso del file dell'archivio chiavi e il percorso della directorytemplates
. Questo esempio include il file dell'archivio chiavi nella directoryresources
. Puoi archiviare il file dove preferisci, ma assicurati di aggiornare il fileapplication.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 dell'archivio chiavi in questo.gitignore
. Nell'esempio fornito, èsecrets/*.p12
(lo scopo dell'archivio chiavi è discusso nella sezione di seguito). Per la procedura dettagliata 2 e successivamente, devi includere anche il percorso del fileclient_secret.json
per assicurarti di non includere i tuoi secret in un repository remoto. Per la procedura dettagliata 3 e successive, devi aggiungere il percorso al file di database H2 e al file di datastore. Per ulteriori informazioni sulla configurazione di questi datastore, consulta la terza procedura dettagliata sulla gestione delle visite ripetute.mvnw
emvnw.cmd
sono gli eseguibili del wrapper Maven per Unix e Windows, rispettivamente. Ad esempio, l'esecuzione di./mvnw --version
su Unix restituisce, tra le altre informazioni, la versione Apache Maven.- La directory
.mvn
contiene la configurazione per il wrapper Maven.
esegui il server di esempio
Devi avviare il server per testarlo. Segui le istruzioni riportate di seguito per eseguire il server di esempio nella lingua che preferisci:
Python
Credenziali OAuth
Crea e scarica le tue credenziali OAuth come descritto sopra. Inserisci il file .json
nella directory root accanto al file di avvio del server dell'applicazione.
Configura il server
Hai a disposizione diverse opzioni per l'esecuzione del server web. Alla fine del file Python, aggiungi uno di questi elementi:
localhost
non protetto. Tieni presente che questa opzione è adatta per i test direttamente solo 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)
Proteggi
localhost
. Devi specificare una tupla di file di chiavi SSL per l'argomentossl_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)
Gunicorn. È adatto per server pronti per la produzione o deployment cloud. Ti consigliamo di impostare una variabile di ambiente
PORT
da utilizzare con questa opzione di lancio.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 per verificare che venga eseguita correttamente.
Node.js
Configura il server
Per eseguire il server tramite HTTPS, devi creare un autocertificato da utilizzare
per eseguire l'applicazione tramite HTTPS. Queste credenziali dovrebbero essere salvate come sslcert/cert.pem
e sslcert/key.pem
nella cartella principale del repository. Potresti dover aggiungere queste chiavi al key chain del sistema operativo affinché il browser le accetti.
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
Questa azione avvia 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 autocertificato da utilizzare per eseguire l'applicazione tramite HTTPS.
Prendi in considerazione l'utilizzo di mkcert per lo sviluppo locale.
Una volta installato mkcert
, i comandi seguenti generano un certificato archiviato in locale per l'esecuzione tramite 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
oppure 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
In questo modo il server viene avviato su https://localhost:5000
o sulla porta specificata in application.properties
.