Configurazione del progetto Google Cloud

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

Per informazioni più generali sulla pubblicazione di un componente aggiuntivo su Marketplace, vedi Pubblicare un'app.

Creazione del progetto 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 "pubblica" e "privata" si riferiscono alla visibilità della tua applicazione in Google Workspace Marketplace; un'applicazione Marketplace privata può essere installata solo dagli utenti all'interno del dominio in cui è stata creata, mentre un'applicazione Marketplace pubblica è disponibile per qualsiasi dominio Google Workspace. Queste devono essere due applicazioni separate, in quanto un progetto non può essere sia pubblico che privato. Le applicazioni pubbliche devono essere esaminate e approvate prima di essere disponibili nel marketplace.

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

Crea un progetto Google Cloud pubblico

Questo progetto rappresenta l'applicazione componente aggiuntivo accessibile da amministratori, insegnanti e studenti. Un progetto pubblico deve essere esaminato e approvato dal team di Google Workspace Marketplace prima di poter essere lanciato o installato.

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

   Crea un progetto Google Cloud

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

   Abilita l'API Classroom

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

   Attivare l'SDK di Google Workspace Marketplace

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

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

6. La tua app verrà esaminata dal team di Google Workspace Marketplace. Ti contatteranno utilizzando l'indirizzo email dello sviluppatore specificato nell'SDK Marketplace. Una volta approvata l'app, deseleziona la casella Non in elenco in modo che insegnanti e amministratori possano trovarla nel Marketplace.

Crea un progetto Google Cloud privato

Questo progetto privato rappresenta l'applicazione del componente aggiuntivo utilizzata per lo sviluppo. Non è accessibile agli utenti al di fuori del dominio in cui è stato creato, ma non deve essere approvato 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 avere accesso a un dominio Google Workspace for Education con la licenza Teaching & Learning 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, eseguire l'upgrade a una licenza Plus e consentire l'accesso all'API dei componenti aggiuntivi di Classroom:

1. Completa i passaggi per ottenere un dominio di test per sviluppatori.

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

   Crea un progetto Google Cloud

   Se non riesci ad accedere a Google Cloud Console o a creare progetti Cloud, controlla 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 unità organizzativa hanno compiuto 18 anni.
   • In App > Servizi Google aggiuntivi:
   • Google Cloud Platform è ATTIVATA per tutti.
   • Le impostazioni per la creazione di progetti sono Consenti agli utenti di creare progetti.
   • Le impostazioni di accesso a Cloud Shell sono Consenti l'accesso a Cloud Shell.

3. Compila e invia il modulo di richiesta di upgrade del dominio demo. L'invio di questo modulo richiede a Google di eseguire l'upgrade del tuo dominio demo a Google Workspace for Education Plus con dieci licenze e consente al tuo progetto Cloud di accedere all'API dei componenti aggiuntivi di Classroom.

   Riceverai un'email al termine delle procedure di upgrade e inserimento nella lista consentita. Assegna le licenze Plus ai tuoi account insegnante di prova nella Console di amministrazione. In Directory > Utenti, crea o seleziona i tuoi account insegnante di prova. Nella sezione Licenze di ogni insegnante, verifica che Google Workspace for Education Plus sia Assegnato.

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

   Abilita l'API Classroom

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

   Attivare l'SDK di Google Workspace Marketplace

6. Imposta Configurazione app Visibilità app su privata nell'SDK di Marketplace.

7. Compila i campi obbligatori nella pagina Scheda dello Store dell'SDK Marketplace e fai clic su PUBBLICA. Una volta pubblicata la scheda dell'app, gli utenti del dominio possono trovare e installare l'app in Google Workspace Marketplace o visitando l'URL dell'app mostrato nella pagina della scheda dello Store.

OAuth 2.0

L'accesso all'API Classroom richiede il consenso all'accesso ai dati utente. Questi vengono ottenuti richiedendo l'accesso di Google 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 Google Workspace Marketplace in modo che l'amministratore di dominio possa fornire il consenso per conto degli utenti del proprio dominio se installano il componente aggiuntivo.

Poiché gli ambiti di Classroom sono sensibili, devi richiedere la verifica OAuth prima di lanciare il componente aggiuntivo. In caso contrario, gli utenti visualizzeranno un messaggio di avviso che l'applicazione non è verificata e solo un numero ridotto di utenti potrà accedere al tuo prodotto. Per ulteriori informazioni sulla verifica, consulta la panoramica della sequenza di revisione.

Consulta la pagina Ambiti OAuth per le API di Google per un elenco dettagliato di tutti gli ambiti disponibili e dei relativi utilizzi. Per informazioni generali sulla configurazione di OAuth, consulta la pagina Configura 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 visualizzare informazioni personali come ritratto, nome e cognome e altre informazioni personali che l'utente ha reso disponibili pubblicamente.

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 passato a qualsiasi URL della tua app web quando viene aperto un iframe. Se un utente non ha autorizzato uno di questi ambiti, login_hint non verrà inviato.

login_hint è un parametro OpenID Connect standard che puoi facoltativamente trasmettere a Google quando utilizzi Google Sign-In o richiedi un token OAuth. Lo scopo è rendere l'esperienza di autorizzazione più fluida 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 l'accesso a tutti i metodi API.
• https://www.googleapis.com/auth/classroom.addons.student, che consente l'accesso alle operazioni di convalida del lancio e di lettura degli allegati.

Anche con un token di accesso OAuth valido che indica le credenziali dell'utente, le chiamate API sono limitate da requisiti aggiuntivi:

• Tutti i metodi richiedono che l'utente sia un insegnante o uno studente del corso specificato da courseId nella richiesta.
• La creazione, l'aggiornamento, l'eliminazione degli allegati e il trasferimento dei voti richiedono 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 del lancio dell'iframe
    • Operazioni di lettura, aggiornamento ed eliminazione degli allegati
    • Aggiornamenti dei voti per quel post
  • Quando viene aperto per la prima volta l'iframe di rilevamento degli allegati, 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 per quanto segue:
    • Creazione di un allegato sotto il post (addOnToken è obbligatorio)
    • Avvia la convalida (addOnToken viene convalidato se fornito ed è obbligatorio quando il componente aggiuntivo non ha un allegato esistente nel post)

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 saperne di più sulla procedura di verifica, consulta le domande frequenti sulla verifica delle API OAuth.

Scheda di Google Workspace Marketplace

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

Considerazioni sulle schede

La scheda dello Store SDK Marketplace del tuo progetto Google Cloud pubblico specifica il nome e le descrizioni della tua applicazione destinate agli utenti finali. Puoi fornire questi dettagli in più lingue nella sezione Dettagli app.

Segui queste linee guida nelle tue schede:

• In Dettagli app:
  • Evita la punteggiatura nel nome dell'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".
  • Descrizione breve e Descrizione dettagliata non devono contenere lo stesso testo.
  • Assicurati di aver selezionato un valore per il campo Prezzi. Questo campo include le opzioni per i prezzi Senza costi, A pagamento con 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 una buona scelta per un componente aggiuntivo di Classroom.
  • Per ulteriori informazioni, consulta gli elementi elencati nella descrizione dei dettagli dell'app di Marketplace.

• In Risorse grafiche:
  • Tutti gli asset grafici forniti non sono sfocati e rispettano le dimensioni specificate negli standard di Google Workspace Marketplace
  • Tutti gli screenshot forniti sono rappresentazioni accurate dell'esperienza con il tuo componente aggiuntivo.
• Nella sezione Link di assistenza:
  • Assicurati di aver fornito un link ai Termini di servizio della tua applicazione.
• Assicurati di rispettare le linee guida per il branding delle API di Google, che riguardano i nomi e le descrizioni consentiti.
• Se fai riferimento a prodotti Google nella tua scheda, utilizza il nome nel formato fornito nell'elenco dei marchi. Assicurati di includere il simbolo del marchio (™) se specificato; utilizza "Google Docs™", non "Google Docs".

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

Se ti interessa integrare le tue applicazioni Google Workspace Marketplace con i servizi di fatturazione e licenze di Google, visita la pagina API Marketplace.

Impostazioni di installazione

I componenti aggiuntivi possono consentire l'installazione individuale oltre a quella dell'amministratore. Questa pagina evidenzia alcune differenze tra i due tipi di installazione. Non ha lo scopo di promuovere un tipo di installazione rispetto all'altro. Puoi scegliere se consentire l'installazione individuale nella pagina di configurazione dell'app dell'SDK di Google Workspace Marketplace.

Installazione amministratore

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

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

• Controlli più rigorosi. Gli amministratori possono limitare gli utenti che possono accedere a un componente aggiuntivo.
• Compatibilità con le licenze. Se la tua applicazione richiede una licenza, l'instradamento 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 da parte di un amministratore riduce il carico di configurazione per insegnanti e studenti. Ciò potrebbe comportare un'esperienza utente più fluida con meno clic e meno opportunità di confusione.

Per saperne di più su come eseguire le installazioni da amministratore, consulta Installare le app del Marketplace nel dominio e Funzionamento della struttura organizzativa per scoprire di più su unità organizzative e gruppi di accesso.

Installazione individuale

Le installazioni individuali 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.

• Facilitare l'adozione. Un maggior numero di utenti può visualizzare e installare il tuo componente aggiuntivo da Google Workspace Marketplace. Consentire l'installazione individuale potrebbe spingere più insegnanti ad adottare o promuovere il tuo prodotto.
• Test dell'amministratore. Un amministratore potrebbe installare individualmente un componente aggiuntivo per testarlo o valutarlo prima di approvarlo o installarlo per un gruppo più ampio.

Oltre a installare i componenti aggiuntivi per conto degli utenti, gli amministratori possono anche gestire una lista consentita per consentire agli utenti di installare componenti aggiuntivi che consentono l'installazione individuale. Se un componente aggiuntivo non è presente nella lista consentita, gli utenti possono comunque visualizzare la scheda del componente aggiuntivo in Google Workspace Marketplace, ma non possono installarlo. Visualizzano invece un messaggio che spiega che l'installazione del componente aggiuntivo non è stata consentita da un amministratore di dominio. Per saperne di più su questo comportamento, vedi Gestire le app di Google Workspace Marketplace 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 avvio nel campo URI di configurazione allegati. Questo URL viene utilizzato come valore src dell'iframe per l'iframe di rilevamento degli allegati. L'iframe Rilevamento allegati viene utilizzato dagli insegnanti per trovare contenuti o attività da allegare al compito. Può essere impostato nella console del progetto Google Cloud.

I prefissi URI dell'allegato consentiti vengono utilizzati per convalidare gli URI impostati in un AddOnAttachment utilizzando i metodi *.addOnAttachments.create e *.addOnAttachments.patch. La convalida è una corrispondenza del prefisso della stringa letterale e non consente l'utilizzo di caratteri jolly.

Devi anche specificare tutti i prefissi URI da cui sono consentiti gli allegati del tuo componente aggiuntivo. Questa funzionalità aumenta la sicurezza impedendo l'apertura di allegati provenienti da origini non autorizzate.

Imposta entrambi i valori nella pagina Configurazione app dell'SDK di Marketplace del tuo progetto Google Cloud.

Account di prova

Crea account di test sul tuo dominio demo per verificare il corretto comportamento del tuo componente aggiuntivo privato. Per testare il passaggio da uno studente all'altro nell'iframe Revisione del lavoro degli studenti, sono necessari due account studente.

Account di prova suggeriti:

• Professoressa Patrizia, tammy.teacher@<your demo domain>
• Sam Student, sam.student@<your demo domain>
• Sally Student, sally.student@<your demo domain>

Segui questa procedura per creare un nuovo account di test:

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 all'interno della Console di amministrazione.

Segui questa procedura per creare un nuovo gruppo di test:

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 all'interno della Console di amministrazione.