Configurazione del progetto Google Cloud

Questa pagina include le informazioni che devi conoscere sulla creazione e la configurazione dei 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 Google), per autorizzare le richieste effettuate dal componente aggiuntivo e per gestire la scheda di un componente aggiuntivo nel Google Workspace Marketplace.

Per informazioni più generali sulla pubblicazione di un componente aggiuntivo su Marketplace, vedi 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 "pubblico" e "privato" si riferiscono alla visibilità dell'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, poiché 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 Crea un progetto Google Cloud.

Creare un progetto Google Cloud pubblico

Questo progetto rappresenta l'applicazione del componente aggiuntivo accessibile ad 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 di Google Workspace Marketplace nel tuo progetto Cloud.

   Abilita l'SDK di Google Workspace Marketplace

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

5. Compila i campi obbligatori nella pagina Scheda del negozio dell'SDK di Marketplace e fai clic su PUBBLICA.

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

Creare 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. Google consiglia pertanto 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 ancora 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 alla console Google Cloud 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 è ATTIVATO 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 dominio demo a Google Workspace for Education Plus con dieci licenze e consente al progetto Cloud di accedere all'API dei componenti aggiuntivi di Classroom.

   Al termine delle procedure di upgrade e inserimento nella lista consentita, riceverai un'email. Assegna le licenze Plus agli account insegnanti di test nella Console di amministrazione. In Directory > Utenti, crea o seleziona gli account insegnanti di test. Nelle **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 di Google Workspace Marketplace nel tuo progetto Cloud.

   Abilita l'SDK di Google Workspace Marketplace

6. Imposta la configurazione dell'app dell'SDK di Marketplace Visibilità dell'app su Privata.

7. Compila i campi obbligatori nella pagina Scheda del negozio dell'SDK di 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 Scheda del negozio.

OAuth 2.0

L'accesso all'API Classroom richiede il consenso per l'accesso ai dati utente. Questi vengono ottenuti richiedendo a Google l'accesso agli ambiti OAuth per l'utente che ha eseguito l'accesso e ricevendo un token che può essere utilizzato in seguito per effettuare 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.

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

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

Dopo che un utente ha autorizzato uno di questi ambiti nel componente aggiuntivo, viene identificato dal parametro di query login_hint. Questo parametro viene passato a tutti gli 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 passare a Google quando utilizzi Accedi con Google 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 per i 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 limitate dai seguenti controlli.
  • Quando un componente aggiuntivo ha già almeno un allegato in un post, può effettuare richieste per:
    • Convalida del lancio di iframe
    • Operazioni di lettura, aggiornamento ed eliminazione degli allegati
    • Aggiornamenti dei voti su quel post
  • Quando l'iframe di rilevamento degli allegati 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 per:
    • Creazione di un allegato nel post (è richiesto addOnToken)
    • Convalida del lancio (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 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 Abilitare e configurare l'SDK di Google Workspace Marketplace e Creare una scheda dello Store di Google Workspace Marketplace.

Considerazioni sulla scheda

La scheda del negozio dell'SDK di Marketplace del tuo progetto Google Cloud pubblico specifica il nome e le descrizioni dell'applicazione destinate agli utenti finali. Puoi fornire questi dettagli in più lingue in Dettagli dell'app.

Segui queste linee guida nelle tue schede:

• In Dettagli dell'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 aggiiornativo" o "Il mio componente aggiuntivo, di La mia azienda".
  • La descrizione breve e la descrizione dettagliata non devono contenere esattamente 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 una prova senza costi, A pagamento con funzionalità senza costi e A pagamento. Non è necessario specificare l'importo del costo nella scheda di Marketplace.
  • Assicurati di aver selezionato un valore per il campo Categoria. Risorse didattiche o Strumenti per insegnanti e amministratori potrebbero essere scelte valide per un componente aggiuntivo di Classroom.
  • Per ulteriori informazioni, consulta gli elementi elencati nella descrizione dei dettagli dell'app di Marketplace.

• In Asset grafici:
  • Tutte le risorse grafiche fornite non sono sfocate e rispettano le dimensioni specificate in the Google Workspace Marketplace standards
  • Tutti gli screenshot forniti sono rappresentazioni accurate dell'esperienza del componente aggiuntivo.
• In 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 "Documenti Google™", non "Documenti Google".

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

Se ti interessa consentire alle tue applicazioni Google Workspace Marketplace di integrarsi con i servizi di licenza e fatturazione di Google, visita API Marketplace.

Impostazioni di installazione

I componenti aggiuntivi possono consentire l'installazione individuale oltre all'installazione dell'amministratore. Questa pagina evidenzia alcune differenze tra i due tipi di installazione. Non ha lo scopo di promuovere nessuno dei due tipi di installazione. Puoi scegliere se consentire l'installazione individuale nella pagina Configurazione dell'app dell'SDK di Google Workspace Marketplace.

Installazione come amministratore

Le installazioni come amministratore 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 come amministratore. L'amministratore può facoltativamente 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 sull'installazione come amministratore.

• Controlli più rigidi. Gli amministratori possono limitare gli utenti che possono accedere a un componente aggiuntivo.
• Compatibilità con le licenze. Se la tua applicazione richiede una licenza, il routing 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 sugli utenti finali. Un'installazione come 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 come amministratore, vedi Installare le app del Marketplace nel tuo dominio e Come funziona la struttura organizzativa per saperne di più sulle unità organizzative e sui 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 sull'installazione individuale.

• Facilitare l'adozione. Un numero maggiore di utenti può visualizzare e installare il tuo componente aggiuntivo da Google Workspace Marketplace. Consentire l'installazione individuale potrebbe spingere un numero maggiore di 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 i 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; vedono 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 saperne di più, consulta la documentazione sulle impostazioni di installazione di Google Workspace Marketplace installation settings documentation per more information.

Integrazione app

Devi fornire un URL di iframe di lancio nel campo URI di configurazione dell'allegato. Questo URL viene utilizzato come valore src dell'iframe per l'iframe di rilevamento degli allegati. L'iframe di rilevamento degli 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 letterale del prefisso della stringa e non consente l'utilizzo di caratteri jolly.

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

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

Account di prova

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

Account di prova suggeriti:

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

Segui questa procedura 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.

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 nella Console di amministrazione.