Configurazione del progetto Google Cloud

Questa pagina include le informazioni necessarie 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 (Google SSO), per autorizzare le richieste effettuate dal componente aggiuntivo e per gestire la scheda di un componente aggiuntivo nel marketplace Google Workspace.

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

Creazione di un progetto Google Cloud

Punto chiave: l'applicazione del componente aggiuntivo di produzione deve avere visibilità public impostata nell'SDK di Google Workspace Marketplace. Un progetto privato può essere utile per sviluppare e testare il tuo componente aggiuntivo, ma è necessario solo un progetto pubblico.

Puoi creare due tipi di progetti: 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. Devono essere due applicazioni distinte, poiché un progetto non può essere sia pubblico che privato. Le applicazioni pubbliche devono essere esaminate e approvate prima di essere disponibili nel marketplace.

Importante: non puoi convertire un progetto privato in uno pubblico.

Per informazioni generali sulla creazione di progetti Google Cloud, consulta Creare un progetto Google Cloud.

Creare un progetto Google Cloud pubblico

Questo progetto rappresenta l'applicazione aggiuntiva 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.

   Creare un progetto Google Cloud

   Importante: assicurati che il progetto appartenga al tuo dominio di produzione e che tu abbia eseguito l'accesso alla console Google Cloud come utente di quel dominio.
   Avviso: per i test devi utilizzare la versione Bozza del progetto. Al momento, la funzionalità di bozza è disponibile solo tramite il Programma di anteprima per sviluppatori di Google Workspace. Dopo aver creato il progetto Cloud, compila il modulo di richiesta per attivare le funzionalità del programma Google Workspace Developer Preview. Per ulteriori informazioni, consulta Aggiornare la scheda dell'app con le bozze.

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

   Attiva l'API Classroom

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

   Attivare l'SDK di Google Workspace Marketplace

4. Imposta l'SDK di Marketplace Configurazione app Visibilità 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: le app non elencate non possono essere trovate in Google Workspace Marketplace tramite la navigazione o la ricerca. Nella configurazione dell'SDK Marketplace puoi trovare un URL diretto che può essere utilizzato per installare il componente aggiuntivo. Solo Google e lo sviluppatore possono trovare la scheda dello Store. L'app deve rimanere non in elenco finché non ti sentirai pronto a rilasciarla al pubblico. Puoi attivare o disattivare l'elenco di un componente aggiuntivo nella pagina Configurazione app dell'SDK Marketplace.

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 inclusa 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 esterni al 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 tuo 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 di prova di Google Workspace for Education, eseguirne 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 gli sviluppatori.

2. Dopo aver eseguito l'accesso come amministratore nel dominio di prova, 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, controlla quanto segue nella Console di amministrazione:

   • Vai alla 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 compiuto 18 anni.
   • In App > Servizi Google aggiuntivi:
   • La piattaforma Google Cloud è attiva 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 di prova a Google Workspace for Education Plus con dieci licenza e consente al tuo progetto Cloud di accedere all' API Componenti aggiuntivi di Classroom.

   Al termine delle procedure di upgrade e inserimento nella lista consentita, riceverai un'email. Assegna le licenze Plus ai tuoi account di insegnante di prova nella Console di amministrazione. In Diretorio > Utenti, crea o seleziona gli account degli insegnanti di prova. In Licenze di ogni insegnante, verifica che Google Workspace for Education Plus sia Assegnato.

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

   Attiva l'API Classroom

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

   Attivare l'SDK di Google Workspace Marketplace

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

7. Compila i campi obbligatori nella pagina Scheda dello Store dell'SDK Marketplace e fai clic su PUBBLICA. Dopo la pubblicazione della 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 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 del dominio possa fornire il consenso per conto degli utenti del dominio se installano il componente aggiuntivo.

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

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

Avviso: se utilizzi un progetto Google Cloud esistente per lo sviluppo di un componente aggiuntivo, non richiedere i nuovi ambiti nel codice per i prodotti esistenti fino al completamento della verifica. Utilizza un flusso di autorizzazione separato, un ambiente di test o imposta un flag di funzionalità per richiedere solo questi ambiti per i percorsi correlati ai componenti aggiuntivi prima di completare la verifica.

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

L'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'app 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 identificati 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.

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

login_hint è un parametro OpenID Connect standard che, facoltativamente, puoi trasmettere a Google quando utilizzi Accedi con Google o richiedi un token OAuth. Lo scopo è semplificare l'esperienza di autorizzazione 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 di accedere a tutti i metodi dell'API.
• https://www.googleapis.com/auth/classroom.addons.student, che consente di accedere 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 soggette a 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 e il trasferimento dei voti degli allegati richiedono che l'utente sia un insegnante.
• Le chiamate a un post specifico di Google Classroom sono soggette ai 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 relativi al 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)
    • Convalida del lancio (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. Pubblica il componente aggiuntivo senza verificare OAuth. In questo modo, il team di revisione di Google Workspace Marketplace viene avvisato di realizzare un video dimostrativo per tuo conto. Il team di revisione ti fornirà il video in modo che tu possa includerlo nell'invio per la verifica OAuth.

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

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

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

Scheda di Google Workspace Marketplace

Avviso: una volta salvata l'opzione di visibilità durante la procedura di pubblicazione, non potrai modificare la selezione in un secondo momento.

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

Considerazioni relative alla scheda

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

Segui queste linee guida nelle tue schede:

• In Dettagli sull'app:

  • Evita i segni di punteggiatura nel nome dell'applicazione. Ad esempio, utilizza "Il mio componente aggiuntivo della mia azienda" anziché "La mia azienda: il mio componente aggiuntivo" o "Il mio componente aggiuntivo della mia azienda".

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

  + Assicurati di aver selezionato un valore per il campo Prezzi. Questo campo include le opzioni 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 del marketplace.

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

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

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

• In Risorse grafiche:

  • Gli asset grafici forniti non sono sfocati e soddisfano le dimensioni specificate gli standard di Google Workspace Marketplace

  • Eventuali screenshot forniti sono rappresentazioni accurate della tua esperienza con il 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 coprono i nomi e le descrizioni consentiti.

• Se nella tua scheda fai riferimento a prodotti Google, utilizza il nome nel formato fornito nell'elenco dei marchi. Assicurati di includere il simbolo della marca (™), se specificato; utilizza "Documenti Google™", non "Documenti Google".

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

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

Impostazioni di installazione

I componenti aggiuntivi possono consentire l'installazione individuale oltre all'installazione da parte dell'amministratore. Questa pagina mette in evidenza alcune differenze tra i due tipi di installazione. Non intende 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 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. Se l'amministratore sceglie di farlo, agli utenti non verrà chiesto di acconsentire a nessuno degli ambiti di accesso.

Di seguito sono riportate alcune considerazioni sull'installazione dell'amministratore.

• Controlli più stringenti. Gli amministratori possono limitare gli utenti che possono accedere a un plug-in.
• Compatibilità con le licenze. Se la tua applicazione richiede una licenza, indirizzare le installazioni tramite un amministratore potrebbe contribuire a garantire che le licenze vengano distribuite e utilizzate in modo appropriato con l'istituto corrispondente.
• Ridurre il carico sugli utenti finali. Un'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 installazioni come amministratore, consulta Installare le app del Marketplace nel dominio e Funzionamento della struttura organizzativa per saperne di più su unità organizzative e gruppi di accesso.

Installazione individuale

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

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. Consentire l'installazione individuale potrebbe spingere più insegnanti ad adottare o consigliare il tuo prodotto.
• Test di amministrazione. Un amministratore potrebbe installare singolarmente 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 singola. Se un componente aggiuntivo non è presente nella lista consentita, gli utenti possono comunque visualizzarne la scheda in Google Workspace Marketplace, ma non possono installarlo. Vedranno 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, consulta Gestire le app di Google Workspace Marketplace nella lista consentita.

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

Integrazione app

Devi fornire un URL iframe di avvio nel campo URI di configurazione degli allegati. Questo URL viene utilizzato come valore src dell'iframe per l'iframe di Discovery degli allegati. L'iframe di Ricerca allegati viene utilizzato dagli insegnanti per trovare contenuti o attività da allegare al compito.

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

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

Account di prova

Crea account di test nel tuo dominio demo per verificare il comportamento corretto del tuo componente aggiuntivo privato. Per testare il passaggio da un account studente all'altro nell'iframe di Revisione dei lavori 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>

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

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.