Creare un componente aggiuntivo di Classroom

Questa è la prima procedura dettagliata della serie di procedure dettagliate sui componenti aggiuntivi di Classroom.

In questa procedura dettagliata, getterai le basi per sviluppare un'applicazione web e pubblicarla come componente aggiuntivo di Classroom. I prossimi passaggi della procedura dettagliata espandono questa app.

Nel corso di questa procedura dettagliata, eseguirai quanto segue:

  • Crea un nuovo progetto Google Cloud per la tua app web.
  • Crea una bozza di app web con pulsanti di accesso segnaposto.
  • Pubblica una scheda dello Store di Google Workspace Marketplace (GWM) privata per la tua app web.

Al termine, puoi installare il componente aggiuntivo e caricarlo nell'iframe dei componenti aggiuntivi di Classroom.

Prerequisiti

Scegli una lingua di seguito per visualizzare i prerequisiti appropriati:

Python

Il nostro esempio Python utilizza il framework Flask. Puoi scaricare il codice sorgente completo per tutte le procedure dettagliate dalla pagina Panoramica. Il codice per questa particolare procedura dettagliata si trova nella directory /flask/01-basic-app/.

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

python -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

Ogni sottodirectory della procedura dettagliata negli esempi scaricati contiene un requirements.txt. Puoi installare rapidamente le librerie richieste utilizzando pip. Utilizza quanto segue per installare le librerie richieste per questa 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 per tutte le procedure dettagliate dalla pagina Panoramica.

Se necessario, installa NodeJS v16.13+.

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 per tutte le procedure dettagliate dalla pagina Panoramica.

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.

Per poter eseguire l'esempio fornito, esegui i comandi seguenti nella directory in cui hai scaricato il progetto, in modo da assicurarti di disporre dei prerequisiti per eseguire il progetto.

java --version
./mvnw --version

Oppure su Windows:

java -version
mvnw.cmd --version

Configura un progetto Google Cloud

L'accesso all'API Classroom e ai metodi di autenticazione richiesti sono controllati dai progetti Google Cloud. Le seguenti istruzioni illustrano i passaggi minimi per creare e configurare un nuovo progetto da utilizzare con il componente aggiuntivo.

Creare il progetto

Crea un nuovo progetto Google Cloud visitando la pagina di creazione del progetto. Puoi specificare qualsiasi nome per il nuovo progetto. Fai clic su Crea.

La creazione completa del nuovo progetto richiede qualche istante. Al termine, assicurati di selezionare il progetto. Puoi sceglierlo nel menu a discesa del selettore del progetto nella parte superiore dello schermo oppure fare clic su SELEZIONA PROGETTO nel menu delle notifiche in alto a destra.

Seleziona il progetto nella console Google Cloud

Collega l'SDK GWM al progetto Google Cloud

Vai al browser della libreria API. Cerca Google Workspace Marketplace SDK. Dovresti vedere l'SDK nell'elenco dei risultati.

La scheda dell'SDK di Google Workspace Marketplace

Seleziona la scheda SDK di Google Workspace Marketplace, quindi fai clic su Attiva.

Configura l'SDK GWM

GWM fornisce la scheda tramite la quale gli utenti e gli amministratori installano il componente aggiuntivo. Per continuare, configura la schermata di consenso OAuth e la configurazione dell'app e la scheda dello Store dell'SDK GWM.

La schermata per il consenso OAuth viene visualizzata quando gli utenti autorizzano per la prima volta la tua app. Viene chiesto loro di consentire all'app di accedere alle proprie informazioni personali e del proprio account, come previsto dagli ambiti attivati.

Vai alla pagina di creazione della schermata per il consenso OAuth. Fornisci le seguenti informazioni:

  • Imposta Tipo di utente su Esterno. Fai clic su Crea.
  • Nella pagina successiva, compila i dettagli dell'app e i dati di contatto richiesti. Fornisci i domini che ospitano la tua app in Domini autorizzati. Fai clic su SALVA E CONTINUA.

  • Aggiungi eventuali ambiti OAuth richiesti dalla tua app web. Consulta la guida alla configurazione di OAuth per una discussione approfondita sugli ambiti e sul loro scopo.

    Devi richiedere almeno uno dei seguenti ambiti affinché Google invii il parametro di query login_hint. Una spiegazione più dettagliata di questo comportamento è disponibile nella nostra guida alla configurazione OAuth:

    • https://www.googleapis.com/auth/userinfo.email (già incluso)
    • https://www.googleapis.com/auth/userinfo.profile (già incluso)

    I seguenti ambiti sono specifici dei componenti aggiuntivi di Classroom:

    • https://www.googleapis.com/auth/classroom.addons.teacher
    • https://www.googleapis.com/auth/classroom.addons.student

    Includi anche qualsiasi altro ambito API di Google che la tua app richiede agli utenti finali.

    Fai clic su SALVA E CONTINUA.

  • Elenca gli indirizzi email di tutti gli account di test nella pagina Utenti di test. Fai clic su SALVA E CONTINUA.

Verifica che le impostazioni siano corrette, quindi torna alla dashboard.

Configurazione dell'app

Vai alla pagina Configurazione app dell'SDK GWM. Fornisci le seguenti informazioni:

  • Imposta Visibilità delle app su Private. Questa impostazione è appropriata per scopi di test e sviluppo ed è la scelta giusta per queste procedure dettagliate. Scegli Public solo se vuoi che il componente aggiuntivo possa essere utilizzato dal pubblico.

  • Imposta Impostazioni di installazione su Admin Only install se desideri limitare l'installazione agli amministratori di dominio.

  • In Integrazione app, seleziona Componente aggiuntivo di Classroom. Ti verrà richiesto l'URI di configurazione dell'allegato protetto; si tratta dell'URL che prevedi venga caricato quando un utente apre il tuo componente aggiuntivo. Ai fini di questa procedura dettagliata, dovrebbe essere https://<your domain>/addon-discovery.

  • I prefissi URI dell'allegato consentiti vengono utilizzati per convalidare gli URI impostati in AddOnAttachment utilizzando i metodi courses.*.addOnAttachments.create e courses.*.addOnAttachments.patch. La convalida è una corrispondenza del prefisso di stringa letterale e non consente l'utilizzo di caratteri jolly in questo momento. Per il momento puoi lasciare vuoti questi campi.

  • Aggiungi gli ambiti OAuth indicati nella schermata per il consenso OAuth nel passaggio precedente.

  • Compila i campi appropriati per la tua organizzazione in Collegamenti per sviluppatori.

Scheda dello store

Vai alla pagina Scheda dello Store dell'SDK GWM. Fornisci le seguenti informazioni:

  • In Dettagli sull'app, aggiungi una lingua o espandi il menu a discesa accanto alla lingua già elencata. Fornisci il nome dell'applicazione e le descrizioni, che vengono visualizzate nella pagina della scheda dello Store GWM del componente aggiuntivo. Fai clic su Fine per salvare.
  • Scegli una Categoria per il componente aggiuntivo.
  • In Asset grafiche, fornisci le immagini per i campi obbligatori. Questi valori possono essere modificati in un secondo momento e possono essere dei segnaposto se hai impostato la visibilità delle app su Privato nel passaggio precedente.
  • In Link di assistenza, fornisci gli URL richiesti. Questi possono essere segnaposto se hai impostato la visibilità dell'app su Privato nel passaggio precedente.

Fai clic su PUBBLICA per salvare le impostazioni. Se hai impostato la visibilità dell'app su Privato nel passaggio precedente, l'app sarà immediatamente disponibile per l'installazione. Se imposti la visibilità dell'app su Pubblica, l'app viene inviata per la revisione da parte del team GWM prima di essere resa disponibile per l'installazione.

Installa componente aggiuntivo

Ora puoi installare il componente aggiuntivo utilizzando il link nella parte superiore della pagina Scheda dello Store dell'SDK GWM. Fai clic su URL app nella parte superiore della pagina per vedere la scheda, poi scegli Installa.

Creare un'app web di base

Configura uno scheletro di applicazione web con due percorsi. I prossimi passaggi della procedura dettagliata espandono questa applicazione, quindi per il momento crea solo una pagina di destinazione per il componente aggiuntivo /addon-discovery e una simulazione della pagina indice / per il nostro "sito aziendale".

Esempio di app web in iframe

Implementa questi due endpoint:

  • /: visualizza un messaggio di benvenuto e un pulsante per chiudere sia la scheda corrente sia l'iframe del componente aggiuntivo.
  • /addon-discovery: visualizza un messaggio di benvenuto e due pulsanti: uno per chiudere l'iframe del componente aggiuntivo e uno per aprire un sito web in una nuova scheda.

Tieni presente che stiamo aggiungendo pulsanti per creare e chiudere finestre o iframe. Questi mostrano un metodo per inserire in modo sicuro l'utente in una nuova scheda per l'autorizzazione nella procedura dettagliata successiva.

Crea script di utilità

Crea una directory static/scripts. Crea un nuovo file addon-utils.js. Aggiungi le due funzioni seguenti.

/**
 *   Opens a given destination route in a new window. This function uses
 *   window.open() so as to force window.opener to retain a reference to the
 *   iframe from which it was called.
 *   @param {string} destinationURL The endpoint to open, or "/" if none is
 *   provided.
 */
function openWebsiteInNewTab(destinationURL = '/') {
  window.open(destinationURL, '_blank');
}

/**
 *   Close the iframe by calling postMessage() in the host Classroom page. This
 *   function can be called directly when in a Classroom add-on iframe.
 *
 *   Alternatively, it can be used to close an add-on iframe in another window.
 *   For example, if an add-on iframe in Window 1 opens a link in a new Window 2
 *   using the openWebsiteInNewTab function above, you can call
 *   window.opener.closeAddonIframe() from Window 2 to close the iframe in Window
 *   1.
 */
function closeAddonIframe() {
  window.parent.postMessage({
    type: 'Classroom',
    action: 'closeIframe',
  }, '*');
};

Crea route

Implementa gli endpoint /addon-discovery e /.

Python

Configura la directory delle applicazioni

Ai fini di questo esempio, struttura la logica dell'applicazione come modulo Python. Questa è la directory webapp nell'esempio fornito.

Crea una directory per il modulo del server, ad esempio webapp. Sposta la directory static nella directory del modulo. Crea una directory template anche nella directory del modulo; i tuoi file HTML verranno spostati qui.

Crea il modulo del server*

Crea il file __init__.py nella directory del modulo e aggiungi le seguenti importazioni e dichiarazioni.

from flask import Flask
import config

app = Flask(__name__)
app.config.from_object(config.Config)

# Load other module script files. This import statement refers to the
# 'routes.py' file described below.
from webapp import routes

Quindi, crea un file per gestire i percorsi dell'app web. webapp/routes.py nell'esempio fornito. Implementa le due route in questo file.

from webapp import app
import flask

@app.route("/")
def index():
    return flask.render_template("index.html",
                                message="You've reached the index page.")

@app.route("/classroom-addon")
def classroom_addon():
    return flask.render_template(
        "addon-discovery.html",
        message="You've reached the addon discovery page.")

Tieni presente che le nostre route trasmettono entrambe una variabile message ai rispettivi modelli Jinja. Questo è utile per identificare la pagina raggiunta dall'utente.

Creare file di configurazione e di avvio

Nella directory root dell'applicazione, crea i file main.py e config.py. Configura la tua chiave segreta in config.py.

import os

class Config(object):
    # Note: A secret key is included in the sample so that it works.
    # If you use this code in your application, replace this with a truly secret
    # key. See https://flask.palletsprojects.com/quickstart/#sessions.
    SECRET_KEY = os.environ.get(
        'SECRET_KEY') or "REPLACE ME - this value is here as a placeholder."

Nel file main.py, importa il modulo e avvia il server Flask.

from webapp import app

if __name__ == "__main__":
    # Run the application over HTTPs with a locally stored certificate and key.
    # Defaults to https://localhost:5000.
    app.run(
        host="localhost",
        ssl_context=("localhost.pem", "localhost-key.pem"),
        debug=True)

Node.js

Le route sono registrate nel file app.js con le seguenti righe.

const websiteRouter = require('./routes/index');
const addonRouter = require('./routes/classroom-addon');

app.use('/', websiteRouter);
app.use('/classroom-addon', addonRouter);

Apri /01-basic-app/routes/index.js ed esamina il codice. Questo percorso viene raggiunto quando l'utente finale visita il sito web aziendale. La route visualizza una risposta utilizzando il modello Handlebar index e passa al modello un oggetto dati contenente le variabili title e message.

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Education Technology',
    message: 'Welcome to our website!'
  });
});

Apri la seconda route /01-basic-app/routes/classroom-addon.js e rivedi il codice. Questo percorso viene raggiunto quando l'utente finale visita il componente aggiuntivo. Tieni presente che questa route utilizza il modello di manubri discovery e anche il layout addon.hbs per visualizzare la pagina in modo diverso rispetto al sito web dell'azienda.

router.get('/', function (req, res, next) {
  res.render('discovery', {
    layout: 'addon.hbs',
    title: 'Education Technology Classroom add-on',
    message: `Welcome.`
});
});

Java

L'esempio di codice Java utilizza moduli per pacchettizzare i passaggi della procedura dettagliata sequenziale. Poiché questa è la prima procedura dettagliata, il codice si trova all'interno del modulo step_01_basic_app. Non è previsto che implementi il progetto utilizzando i moduli; ti consigliamo piuttosto di creare su un unico progetto man mano che segui ogni passaggio della procedura dettagliata.

Crea una classe controller, Controller.java in questo progetto di esempio, per definire gli endpoint. In questo file, importa l'annotazione @GetMapping dalla dipendenza spring-boot-starter-web.

import org.springframework.web.bind.annotation.GetMapping;

Includi l'annotazione del controller del framework Spring sopra la definizione della classe per indicare lo scopo della classe.

@org.springframework.stereotype.Controller
public class Controller {

Quindi implementa le due route e una route aggiuntiva per la gestione degli errori.

/** Returns the index page that will be displayed when the add-on opens in a
*   new tab.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the index page template if successful, or the onError method to
*   handle and display the error message.
*/
@GetMapping(value = {"/"})
public String index(Model model) {
  try {
    return "index";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Returns the add-on discovery page that will be displayed when the iframe
*   is first opened in Classroom.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the addon-discovery page.
*/
@GetMapping(value = {"/addon-discovery"})
public String addon_discovery(Model model) {
  try {
    return "addon-discovery";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Handles application errors.
*   @param errorMessage message to be displayed on the error page.
*   @param model the Model interface to pass error information to display on
*   the error page.
*   @return the error page.
*/
@GetMapping(value = {"/error"})
public String onError(String errorMessage, Model model) {
  model.addAttribute("error", errorMessage);
  return "error";
}

Testa il componente aggiuntivo

Avvia il server. Quindi, accedi a Google Classroom come utente di test per l'insegnante. Vai alla scheda Lavori del corso e crea un nuovo Compito. Fai clic sul pulsante Componenti aggiuntivi sotto l'area di testo e seleziona il componente aggiuntivo. L'iframe si apre e il componente aggiuntivo carica l'URI di configurazione dell'allegato che hai specificato nella pagina Configurazione app dell'SDK GWM.

Complimenti! È tutto pronto per il passaggio successivo: accesso degli utenti con Google SSO.