Configurazione del progetto Google Cloud

Questa pagina contiene le informazioni necessarie per creare e configurare i componenti aggiuntivi di Google Cloud per Classroom. I progetti Google Cloud vengono utilizzati per implementare Google Single Sign-On tramite OAuth 2.0 (SSO di Google), per autorizzare le richieste effettuate dal componente aggiuntivo e gestire la scheda di un componente aggiuntivo nello store di Google Workspace Marketplace.

Per informazioni più generali sulla pubblicazione di un componente aggiuntivo nel Marketplace, visita la pagina Pubblicare un'app.

Creazione di progetti Google Cloud

Esistono due tipi di progetti da creare: un progetto privato utilizzato per lo sviluppo e un progetto pubblico raggiungibile dagli utenti finali. Le etichette "pubbliche" e "private" si riferiscono alla visibilità della tua applicazione in Google Workspace Marketplace; un'applicazione del Marketplace privata può essere installata solo dagli utenti all'interno del dominio in cui è stata creata, mentre un'applicazione pubblica del Marketplace è disponibile per qualsiasi dominio Google Workspace. Devono essere due applicazioni separate, poiché un progetto non può essere pubblico e privato. Le domande pubbliche devono essere esaminate e approvate prima di essere disponibili sul Marketplace.

Importante: non puoi convertire un progetto privato in un progetto pubblico. Crea un progetto privato per lo sviluppo del tuo componente aggiuntivo e uno pubblico che rappresenti la versione pronta per la produzione.

Per informazioni generali sulla creazione di progetti Google Cloud, visita la pagina Creare un progetto Google Cloud.

Crea un progetto Google Cloud privato

Questo progetto privato rappresenta l'applicazione del componente aggiuntivo utilizzata per lo sviluppo. Non è accessibile agli utenti esterni al dominio in cui è stato creato, ma non è necessaria la sua approvazione prima dell'installazione. Pertanto, Google consiglia di utilizzare questo progetto per sviluppare e testare il componente aggiuntivo in un ambiente controllato.

Per creare un progetto privato, devi accedere a un dominio Google Workspace for Education con licenza Teaching & Learning Upgrade o Plus. Se non hai già accesso a un dominio di questo tipo, segui questi passaggi per configurare un dominio demo di Google Workspace for Education, esegui l'upgrade a una licenza Plus e consenti l'accesso all'API Classroom add-ons:

1. Completa i passaggi per ricevere un dominio di prova per sviluppatori.

2. Dopo aver eseguito l'accesso come amministratore nel dominio demo, crea un nuovo progetto Google Cloud.

   Creare un progetto Google Cloud

   Avviso: assicurati che il progetto appartenga al dominio demo e di aver eseguito l'accesso alla console Google Cloud utilizzando un account amministratore del dominio demo.

   Se non riesci ad accedere alla console Google Cloud o a creare progetti Cloud, verifica quanto segue nella Console di amministrazione:

   • Visita la pagina Impostazioni account > Impostazioni di accesso in base all'età e seleziona l'opzione Tutti gli utenti di questo gruppo o di questa unità organizzativa hanno almeno 18 anni.
   • In App > Servizi Google aggiuntivi:
     • La piattaforma Google Cloud è ON per tutti.
     • Le impostazioni per la creazione del progetto sono impostate su Consenti agli utenti di creare progetti.
     • Le impostazioni di accesso di Cloud Shell sono Consenti l'accesso a Cloud Shell.

3. Compila e invia il modulo di richiesta di upgrade del dominio demo. Inviando questo modulo, consenti a Google di eseguire l'upgrade del dominio demo a Google Workspace for Education Plus con dieci licenze e permette al tuo progetto Cloud di accedere all'API Classroom add-ons.

   Nota: invia sia il modulo per i domini demo di Google for Education dalla pagina Richiedi un dominio di prova per sviluppatori sia il modulo di richiesta di upgrade del dominio demo discusso qui.

   Riceverai un'email quando i processi per l'upgrade e la lista consentita saranno completati. Assegna licenze Plus agli account insegnante di prova nella Console di amministrazione. In Directory > Utenti, crea o seleziona gli account insegnante di test. Nelle Licenze di ogni insegnante, verifica che Google Workspace for Education Plus sia Assegnato.

4. Attivare l'API Classroom nel tuo progetto Cloud.

   Attivare l'API Classroom

5. Abilita l'SDK di Google Workspace Marketplace nel tuo progetto Cloud.

   Attiva l'SDK di Google Workspace Marketplace

6. Imposta Configurazione delle app Visibilità delle app dell'SDK Marketplace su privato.

7. Compila i campi obbligatori nella pagina Scheda dello Store dell'SDK di Marketplace e fai clic su PUBBLICA. Dopo la pubblicazione della scheda dell'app, gli utenti del dominio possono trovarla e installarla nel Google Workspace Marketplace o visitando l'URL dell'app mostrato nella pagina della scheda dello Store.

Creare un progetto Google Cloud pubblico

Questo progetto rappresenta l'applicazione del componente aggiuntivo accessibile da amministratori, insegnanti e studenti.

1. Crea un nuovo progetto Google Cloud nel tuo dominio di produzione.

   Creare un progetto Google Cloud

   Avviso: assicurati che il progetto appartenga al dominio di produzione e di aver eseguito l'accesso alla console Google Cloud come utente di quel dominio.

2. Attivare l'API Classroom nel tuo progetto Cloud.

   Attivare l'API Classroom

3. Abilita l'SDK di Google Workspace Marketplace nel tuo progetto Cloud.

   Attiva l'SDK di Google Workspace Marketplace

4. Imposta la Configurazione delle app dell'SDK di Marketplace per Visibilità delle app su Pubblico e seleziona la casella Non in elenco.

   Punto chiave: non puoi condividere o convertire un progetto privato utilizzato durante lo sviluppo e i test interni.
   Punto chiave: non puoi trovare app non in elenco in Google Workspace Marketplace sfogliando o cercando. All'interno della configurazione dell'SDK di Marketplace, puoi trovare un URL diretto che puoi utilizzare per installare il componente aggiuntivo. Solo Google e lo sviluppatore possono trovare la scheda dello Store. L'app dovrebbe rimanere non in elenco finché non decidi di rilasciarla al pubblico. Puoi attivare o disattivare un componente aggiuntivo nella pagina Configurazione app dell'SDK Marketplace.

5. Condividi l'ID o il numero del progetto Cloud con il tuo partner di Google per aggiungere il progetto alla lista consentita dei componenti aggiuntivi. In questo modo, il progetto potrà accedere alle nuove funzionalità dei componenti aggiuntivi dell'API Classroom.

6. Compila i campi obbligatori nella pagina Scheda dello Store dell'SDK di Marketplace e fai clic su PUBBLICA.

7. La tua app verrà esaminata dal team di Google Workspace Marketplace. Comunicherà con te utilizzando l'indirizzo email dello sviluppatore specificato nell'SDK di Marketplace. Dopo l'approvazione dell'app, deseleziona la casella Non in elenco in modo che insegnanti e amministratori possano trovarla nel Marketplace.

OAuth 2.0

L'accesso all'API Classroom richiede il consenso per l'accesso ai dati utente. Questi si ottengono richiedendo a Google l'accesso agli ambiti OAuth per l'utente che ha eseguito l'accesso e ricevendo un token che può essere utilizzato per effettuare successivamente chiamate API a Google Classroom. Gli ambiti devono essere configurati nella scheda dello Store di Google Workspace Marketplace in modo che l'amministratore di dominio possa fornire il consenso per conto degli utenti del dominio se installano il componente aggiuntivo.

Importante: se il componente aggiuntivo richiede ambiti aggiuntivi, includili nella schermata per il consenso OAuth, nella scheda Configurazione app dell'SDK del Marketplace e nel codice dell'applicazione del componente aggiuntivo. La mancata corrispondenza degli ambiti in queste località potrebbe causare problemi agli utenti durante l'installazione dei componenti aggiuntivi.

Consulta la pagina Ambiti OAuth per API di Google per un elenco dettagliato di tutti gli ambiti disponibili e dei loro utilizzi. Per informazioni generali sulla configurazione di OAuth, consulta la pagina Configurare OAuth nella documentazione di Workspace.

Autorizzazioni utente

La tua app web deve richiedere almeno uno dei seguenti ambiti:

• https://www.googleapis.com/auth/userinfo.email, che consente a un'applicazione di visualizzare l'indirizzo email dell'utente.
• https://www.googleapis.com/auth/userinfo.profile, che consente a un'applicazione di accedere a informazioni personali come ritratto, nome e cognome e altre informazioni personali che l'utente ha reso pubblicamente disponibili.

Dopo che un utente ha autorizzato uno di questi ambiti nel tuo componente aggiuntivo, viene identificato dal parametro di query login_hint. Questo parametro viene trasmesso a qualsiasi URL dell'app web quando viene aperto un iframe. Se un utente non ha autorizzato uno di questi ambiti, il parametro hd ("dominio ospitato") viene invece trasmesso agli URL della tua app web.

Avviso: la tua app deve richiedere almeno uno degli ambiti userinfo.email o userinfo.profile per ricevere login_hint nelle visite successive dello stesso utente.

login_hint e hd sono parametri OpenID Connect standard che puoi passare facoltativamente a Google quando utilizzi Accedi con Google o richiedi un token OAuth. Hanno lo scopo di rendere più semplice l'esperienza di autorizzazione per l'utente finale.

Ambiti dei componenti aggiuntivi di Classroom

I seguenti ambiti sono specifici dei componenti aggiuntivi di Classroom:

• https://www.googleapis.com/auth/classroom.addons.teacher, che consente di accedere a tutti i metodi API.
• https://www.googleapis.com/auth/classroom.addons.student, che consente di accedere alle operazioni di convalida e lettura degli allegati.

Anche se un token di accesso OAuth valido indica le credenziali dell'utente, le chiamate API sono soggette a requisiti aggiuntivi:

• Tutti i metodi richiedono che l'utente sia un insegnante o uno studente del corso specificato da courseId nella richiesta.
• Per la creazione, l'aggiornamento, l'eliminazione e l'invio dei voti degli allegati è necessario che l'utente sia un insegnante.
• Le chiamate a un post specifico di Google Classroom sono controllate dai seguenti controlli.
  • Quando un componente aggiuntivo ha già almeno un allegato in un post, può effettuare richieste per:
    • Convalida lancio iframe
    • Operazioni di lettura, aggiornamento ed eliminazione degli allegati
    • Valuta gli aggiornamenti sul post
  • Quando l'iframe Attachment Discovery viene aperto per la prima volta, il componente aggiuntivo potrebbe non avere ancora un allegato nel post. Viene fornito un parametro di query addOnToken che può essere utilizzato per effettuare richieste di quanto segue:
    • Creazione di un allegato sotto il post (addOnToken è obbligatorio)
    • Avvia la convalida (il campo addOnToken viene convalidato se fornito ed è obbligatorio quando il componente aggiuntivo non ha un allegato esistente nel post)

Verifica OAuth

Nota: non puoi creare un video dimostrativo da inviare nell'ambito della procedura di verifica OAuth. Devi pubblicare il componente aggiuntivo senza verificare OAuth. In questo modo il team di revisori di Google Workspace Marketplace potrà realizzare un video dimostrativo per tuo conto. Il team di revisione ti fornirà quindi il video in modo che tu possa includerlo nell'invio della verifica OAuth.

Un componente aggiuntivo di Classroom utilizza le API di Google per accedere ai dati degli utenti Google.

• Verifica l'identità del tuo brand.
• Verifica gli ambiti OAuth sensibili.

Per ulteriori informazioni sul processo di verifica, consulta le domande frequenti sulla verifica dell'API OAuth.

Scheda di Google Workspace Marketplace

Avviso: dopo aver salvato l'opzione di visibilità durante il processo di pubblicazione, non potrai modificare la selezione in un secondo momento.

Ci sono alcuni aspetti da considerare durante la creazione di una scheda dello Store del Marketplace per i componenti aggiuntivi di Classroom durante il programma di accesso in anteprima.

Per informazioni generali sulla configurazione dell'SDK di Google Workspace Marketplace, visita la pagina Attivare e configurare l'SDK di Google Workspace Marketplace e Creare una scheda dello Store di Google Workspace Marketplace.

Considerazioni sulla scheda

La scheda pubblica dello store di SDK Marketplace del tuo progetto Google Cloud specifica il nome e le descrizioni dell'applicazione destinati agli utenti finali. Puoi fornire questi dettagli in più lingue nella sezione Dettagli sull'app.

Segui queste linee guida nelle tue schede:

• In Dettagli sull'app:

  • Evita la punteggiatura in Nome applicazione. Ad esempio, utilizza "Il mio componente aggiuntivo di La mia azienda" anziché "La mia azienda: Il mio componente aggiuntivo" o "Il mio componente aggiuntivo di La mia azienda".

  • La descrizione breve e la descrizione dettagliata non devono contenere lo stesso testo.

  • Assicurati di aver selezionato un valore per il campo Pricing (Prezzi). Questo campo include le opzioni Senza costi, Pagato con una prova senza costi, A pagamento con funzionalità senza costi e A pagamento. Non è necessario specificare l'importo del costo nella scheda del Marketplace.

  • Assicurati di aver selezionato un valore per il campo Categoria. Risorse accademiche o Strumenti per insegnanti e amministratori potrebbero essere ottime alternative per un componente aggiuntivo di Classroom.

  • Per ulteriori informazioni, consulta gli elementi elencati nella descrizione dei dettagli dell'app di Marketplace.

Importante: controlla i dettagli dell'app per ogni lingua in cui offri il componente aggiuntivo.

• In Risorse grafiche:

  • Tutte le risorse grafiche fornite non sono sfocate e soddisfano le dimensioni specificate negli standard di Google Workspace Marketplace

  • Gli screenshot forniti sono rappresentazioni accurate dell'esperienza con il componente aggiuntivo.

• In Link per l'assistenza:

  • Assicurati di aver fornito un link ai Termini di servizio dell'applicazione.

• Assicurati di rispettare le linee guida per il branding dell'API di Google, che regolano i nomi e le descrizioni consentiti.

• Se nella scheda fai riferimento a un prodotto Google, utilizza il nome nel formato indicato nell'elenco dei marchi. Assicurati di includere il simbolo del marchio (TM), se specificato; utilizza "Documenti GoogleTM", non "Documenti Google".

Eseguire l'integrazione con i servizi di licenza e fatturazione di Google

Se vuoi consentire l'integrazione delle tue applicazioni Google Workspace Marketplace con i servizi di licenza e fatturazione di Google, visita l' API Marketplace.

Impostazioni di installazione

I componenti aggiuntivi possono consentire l'installazione singola oltre a quella dell'amministratore. Questa pagina evidenzia alcune differenze tra i due tipi di installazione. Non è destinata a promuovere nessuno dei due tipi di installazione. Puoi scegliere se consentire l'installazione singola nella pagina Configurazione app dell'SDK di Google Workspace Marketplace.

Installazione da parte dell'amministratore

Le installazioni amministrative consentono a un amministratore di aggiungere un componente aggiuntivo a tutti gli account di un dominio o a unità organizzative o gruppi di accesso specifici. Solo un amministratore di dominio può eseguire un'installazione amministrativa. L'amministratore può scegliere di acconsentire a tutti gli ambiti di accesso per conto di tutti gli utenti del dominio; agli utenti non viene richiesto di fornire il consenso per alcun ambito di accesso, se l'amministratore sceglie di farlo.

Di seguito sono riportate alcune considerazioni relative all'installazione da parte dell'amministratore.

• Controlli più stringenti. Gli amministratori possono limitare gli utenti che possono accedere a un componente aggiuntivo.
• Compatibilità con le licenze. Se la tua applicazione richiede una licenza, la gestione del canale delle installazioni tramite un amministratore potrebbe contribuire a garantire che le licenze vengano distribuite e utilizzate in modo appropriato con l'istituto corrispondente.
• Minore carico per gli utenti finali. L'installazione eseguita dall'amministratore riduce il carico di configurazione per insegnanti e studenti. L'esperienza utente potrebbe essere più fluida, con meno clic e meno possibilità di creare confusione.

Vedi Installare le app del Marketplace nel dominio per ulteriori informazioni su come eseguire installazioni per gli amministratori e Funzionamento della struttura organizzativa per saperne di più sulle unità organizzative e sui gruppi di accesso.

Installazione individuale

Le installazioni singole aggiungono un componente aggiuntivo all'account dell'utente. All'utente viene chiesto di acconsentire agli ambiti di accesso del componente aggiuntivo durante l'installazione.

Di seguito sono riportate alcune considerazioni relative all'installazione individuale.

• Facilita l'adozione. Più utenti possono vedere e installare il tuo componente aggiuntivo da Google Workspace Marketplace. Se consenti l'installazione individuale, più insegnanti potrebbero adottare o sostenere il tuo prodotto.
• Test dell'amministratore. Un amministratore può installare singolarmente un componente aggiuntivo per testarlo o valutarlo prima di approvarlo o installarlo per un gruppo più ampio.

Oltre a installare componenti aggiuntivi per conto degli utenti, gli amministratori possono anche mantenere una lista consentita per consentire agli utenti di installare componenti aggiuntivi che consentono l'installazione individuale. Se un componente aggiuntivo non è nella lista consentita, gli utenti possono comunque vederne la relativa scheda in Google Workspace Marketplace, ma non possono installarlo; viene invece visualizzato un messaggio che spiega che l'installazione del componente aggiuntivo non è stata autorizzata da un amministratore di dominio. Per scoprire di più su questo comportamento, consulta Gestire le app di Google Workspace Marketplace inserite nella lista consentita.

Per ulteriori informazioni, consulta la documentazione sulle impostazioni di installazione di Google Workspace Marketplace.

Integrazione app

Devi fornire un URL iframe di lancio nel campo URI configurazione allegato. Questo URL viene utilizzato come valore src iframe per l'iframe di rilevamento degli allegati. L'iframe Attachment Discovery viene utilizzato dagli insegnanti per trovare contenuti o attività da allegare ai compiti.

Devi inoltre specificare tutti i prefissi URI da cui sono consentiti gli allegati dal componente aggiuntivo. Questa funzionalità rafforza la sicurezza impedendo gli allegati provenienti da origini non autorizzate.

Per ulteriori informazioni su questi campi, consulta la pagina della guida agli iframe.

Account di prova

Crea account di prova nel tuo dominio dimostrativo per verificare il comportamento corretto del tuo componente aggiuntivo privato. Sono necessari due account studente per testare il passaggio da uno studente all'altro nell'iframe Recensione del lavoro dello studente.

Account di prova suggeriti:

• Tamara Insegnante, mario.insegnante@<dominio demo>
• Sam Student, sam.student@<dominio demo>
• Sally Studente, sally.student@<dominio demo>

Per creare un nuovo account di prova:

1. Accedi alla Console di amministrazione.
2. Vai a Utenti.
3. Fai clic su Aggiungi nuovo utente (vedi Figura 1).
4. Inserisci le informazioni dell'utente e assegna i ruoli appropriati.

Figura 1. Posizione del link Aggiungi nuovo utente nella Console di amministrazione.

Per creare un nuovo gruppo di test, segui questa procedura:

1. Accedi alla Console di amministrazione.
2. Vai a Gruppi.
3. Fai clic su Crea gruppo (vedi Figura 2).
4. Inserisci i membri e i proprietari del gruppo.

Figura 2. Posizione del link Crea gruppo nella Console di amministrazione.