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, crei le basi per lo sviluppo di un'applicazione web e la sua pubblicazione come componente aggiuntivo di Classroom. I passaggi futuri della procedura dettagliata espandono questa app.

Nel corso di questa procedura dettagliata, completerai le seguenti operazioni:

• Crea un nuovo progetto Google Cloud per il tuo componente aggiuntivo.
• Crea un'app web scheletrica con pulsanti di accesso segnaposto.
• Pubblica una scheda dello store di Google Workspace Marketplace per il tuo componente aggiuntivo.

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

Prerequisiti

Scegli una lingua per visualizzare i prerequisiti appropriati:

python -m ensurepip --upgrade

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

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

npm install

java --version
./mvnw --version

java -version
mvnw.cmd --version

Configura un progetto Google Cloud

L'accesso all'API Classroom e ai metodi di autenticazione richiesti è controllato dai progetti Google Cloud. Le seguenti istruzioni ti guidano attraverso i passaggi minimi per creare e configurare un nuovo progetto da utilizzare con il tuo componente aggiuntivo.

Crea il progetto

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

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

Collega l'SDK di Google Workspace Marketplace al progetto Google Cloud

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

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

Configura l'SDK di Google Workspace Marketplace

Google Workspace Marketplace fornisce la scheda tramite la quale utenti e amministratori installano il tuo componente aggiuntivo. Per procedere, configura la configurazione dell'app e la scheda dello store dell'SDK Marketplace e la schermata per il consenso OAuth.

Configurazione dell'app

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

• Imposta la visibilità dell'app su Public o Private.

  • L'impostazione pubblica è destinata alle app che verranno rilasciate agli utenti finali. Un'app pubblica deve essere sottoposta a una procedura di approvazione prima di essere pubblicata per gli utenti finali, ma puoi specificare gli utenti che possono installarla e testarla come bozza. Si tratta di uno stato di pre-pubblicazione che ti consentirà di testare e sviluppare il componente aggiuntivo prima di inviarlo per l'approvazione.
  • L'impostazione privata è adatta per i test e lo sviluppo interni. Un'app privata può essere installata solo dagli utenti dello stesso dominio in cui è stato creato il progetto. Pertanto, devi impostare la visibilità su privata solo se il progetto è stato creato in un dominio con un abbonamento a Google Workspace for Education subscription, altrimenti gli utenti di test non potranno avviare i componenti aggiuntivi di Classroom.

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

• In Integrazione dell'app, seleziona Componente aggiuntivo di Classroom. Ti viene richiesto l'URI di configurazione dell'allegato sicuro ; questo è l'URL che prevedi di caricare quando un utente apre il tuo componente aggiuntivo. Ai fini di questa procedura dettagliata, deve 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 letterale del prefisso della stringa e al momento non consente l'utilizzo di caratteri jolly. Aggiungi almeno il dominio principale del server dei contenuti, ad esempio https://localhost:5000/ o https://cdn.myedtech.com/.

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

• Compila i campi in base alla tua organizzazione in Link dello sviluppatore.

Scheda dello store

Vai alla pagina Scheda dello store dell'SDK Marketplace. Fornisci le seguenti informazioni:

• In Dettagli dell'app, aggiungi una lingua o espandi il menu a discesa accanto alla lingua già elencata. Fornisci un nome dell'applicazione e le descrizioni; questi vengono visualizzati nella pagina della scheda dello store di Google Workspace Marketplace del tuo componente aggiuntivo. Fai clic su Fine per salvare.
• Scegli una categoria per il tuo componente aggiuntivo.
• In Risorse grafiche, fornisci le immagini per i campi obbligatori. Questi possono essere modificati in un secondo momento e possono essere segnaposto per il momento.
• In Link di assistenza, fornisci gli URL richiesti. Questi possono essere segnaposto se nel passaggio precedente hai impostato la visibilità dell'app su Privata.

Se nel passaggio precedente hai impostato la visibilità dell'app su Privata, fai clic PUBBLICA; la tua app è immediatamente disponibile per l'installazione. Se hai impostato la visibilità dell'app su Pubblica, aggiungi gli indirizzi email nell'area Tester bozza per tutti gli utenti di test e fai clic su Salva bozza.

Schermata per il consenso OAuth

La schermata per il consenso OAuth viene visualizzata quando gli utenti autorizzano per la prima volta la tua app. Viene chiesto loro di consentire alla tua app di accedere alle loro informazioni personali e dell'account, come stabilito dagli ambiti che attivi.

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 tutti i domini che ospitano la tua app in Domini autorizzati. Fai clic su SALVA E CONTINUA.

• Aggiungi gli ambiti OAuth richiesti dalla tua app web. Per una discussione approfondita degli ambiti e del loro scopo, consulta la guida alla configurazione di OAuth.

  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 di OAuth:

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

  I seguenti ambiti sono specifici per i componenti aggiuntivi di Classroom:

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

  Includi anche tutti gli altri ambiti delle API Google richiesti dalla tua app 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.

Installazione del componente aggiuntivo

Ora puoi installare il componente aggiuntivo utilizzando il link nella parte superiore della pagina della scheda dello store dell'SDK Marketplace. Fai clic su Visualizza in Marketplace nella parte superiore della pagina per visualizzare la scheda, quindi scegli Installa.

Crea un'app web di base

Configura un'applicazione web scheletrica con due route. I passaggi futuri della procedura dettagliata espandono questa applicazione, quindi per ora crea solo una pagina di destinazione per il componente aggiuntivo /addon-discovery e una pagina indice fittizia / per il nostro "sito aziendale".

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 l'iframe. Questi dimostrano un metodo per portare in sicurezza 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 seguenti due funzioni.

/**
 *   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, 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 /.

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

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

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

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)

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

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

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

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

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

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

/** 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. Poi, accedi a Google Classroom come uno degli utenti di test Insegnante. Vai alla scheda Lavori del corso e crea un nuovo Compito. Seleziona il componente aggiuntivo dal selettore Componenti aggiuntivi. L'iframe si apre e il componente aggiuntivo carica l'URI di configurazione dell'allegato specificato nella pagina di configurazione dell'app dell'SDK Marketplace.

Complimenti! Ora puoi procedere al passaggio successivo: l'accesso degli utenti con il servizio SSO di Google.