Configurazione del progetto Google Cloud

Questa pagina contiene 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 servizio 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 di Google Workspace Marketplace.

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

Creazione di progetti Google Cloud

Punto chiave :l'applicazione del componente aggiuntivo di produzione deve avere la visibilità pubblica impostata nell'SDK di Google Workspace Marketplace. Un progetto privato può essere utile per lo sviluppo e il test del componente aggiuntivo, ma solo uno pubblico è obbligatorio.

Ci sono 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 del Marketplace privata può essere installata solo dagli utenti all'interno del dominio in cui è stata creata, mentre un'applicazione del Marketplace pubblica è disponibile per qualsiasi dominio Google Workspace. Devono essere due applicazioni separate, dato che un progetto non può essere sia pubblico sia privato. Le applicazioni pubbliche devono essere esaminate e approvate prima di essere disponibili sul Marketplace.

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

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

Crea un progetto Google Cloud pubblico

Questo progetto rappresenta l'applicazione del 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 avviato 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 di aver eseguito l'accesso alla console Google Cloud come utente di quel dominio.
   Avviso: devi utilizzare la versione Bozza del progetto per i test. Al momento, la funzionalità Bozza è disponibile solo tramite il Programma Anteprima per gli sviluppatori di Google Workspace. Dopo aver creato il progetto Cloud, compila il modulo di richiesta per attivare le funzionalità del Programma Anteprima per gli sviluppatori di Google Workspace. Per maggiori informazioni, consulta Aggiornare la scheda dell'app con le bozze.

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

   Attivare l'API Classroom

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

   Attivare l'SDK Google Workspace Marketplace

4. Imposta l'opzione Configurazione app Visibilità app dell'SDK Marketplace su Pubblica 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 è possibile trovare app non in elenco in Google Workspace Marketplace sfogliando i contenuti o eseguendo ricerche. All'interno della 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. La tua app dovrebbe rimanere non in elenco finché non potrai rilasciarla al pubblico. Puoi scegliere se elencare un componente aggiuntivo nella pagina Configurazione app dell'SDK di 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. Comunicheranno con te utilizzando l'indirizzo email dello sviluppatore specificato nell'SDK di Marketplace. Dopo che l'app è stata approvata, 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 esterni al dominio in cui è stato creato, ma non deve essere approvata prima dell'installazione. Google consiglia quindi 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 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, eseguirne l'upgrade a una licenza Plus e consentire l'accesso all'API Classroom componenti aggiuntivi:

1. Completa i passaggi per richiedere 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 dei 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. Con l'invio di questo modulo, Google deve eseguire l'upgrade del tuo dominio dimostrativo a Google Workspace for Education Plus con dieci licenze e consentire l'accesso del tuo progetto Cloud all'API dei componenti aggiuntivi di Classroom.

   Riceverai un'email al termine dei processi di upgrade e lista consentita. Assegna licenze Plus agli account degli insegnanti di prova nella Console di amministrazione. In Directory > Utenti, crea o seleziona gli account degli insegnanti di prova. Nelle Licenze di ogni insegnante, verifica che Google Workspace for Education Plus sia Assegnato.

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

   Attivare l'API Classroom

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

   Attivare l'SDK Google Workspace Marketplace

6. Imposta l'opzione Configurazione app Visibilità app dell'SDK Marketplace su private.

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

OAuth 2.0

L'accesso all'API Classroom richiede il consenso all'accesso ai dati utente. Questi risultati 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 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 suo dominio se installano il componente aggiuntivo.

Importante: se il componente aggiuntivo richiede ambiti aggiuntivi, includili nella schermata di consenso OAuth, nella scheda Configurazione app SDK 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 le API di Google per un elenco dettagliato di tutti gli ambiti disponibili e i loro utilizzi. Per informazioni generali sulla configurazione di OAuth, consulta la pagina Configura OAuth nella documentazione di Workspace.

Autorizzazioni dell'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 nome e cognome, nonché 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 dell'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 poter ricevere login_hint nelle visite successive dello stesso utente.

login_hint è un parametro OpenID Connect standard che puoi passare facoltativamente a Google quando utilizzi Accedi con Google o richiedi un token OAuth. Ha lo scopo di 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 dell'API.
• https://www.googleapis.com/auth/classroom.addons.student, che consente di accedere per avviare le operazioni di convalida e 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 dal courseId nella richiesta.
• Per la creazione, l'aggiornamento, l'eliminazione e il trasferimento dei voti degli allegati è necessario che l'utente sia un insegnante.
• Le chiamate a un post specifico di Google Classroom vengono 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
    • Aggiornamenti dei voti per quel post
  • Alla prima apertura dell'iframe di rilevamento dell'allegato, 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 convalida (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 invece pubblicare il componente aggiuntivo senza verificare OAuth. In questo modo avvisiamo al team di revisione di Google Workspace Marketplace di realizzare un video dimostrativo per tuo conto. Il team di revisione ti fornisce quindi il video in modo che tu possa includerlo nella richiesta di 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 sulla procedura 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 più modificare la selezione.

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 sulle schede

La scheda di archiviazione dell'SDK Marketplace del tuo progetto Google Cloud pubblico specifica il nome e le descrizioni dell'applicazione per gli 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 nel nome dell'applicazione. Ad esempio, utilizza "Il mio componente aggiuntivo della mia azienda" invece di "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 esattamente lo stesso testo.

  + Assicurati di aver selezionato un valore per il campo Pricing (Prezzi). Questo campo include le opzioni per i prezzi Senza costi, Pagato con una prova senza costi, Pagato 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 accademiche o Strumenti per insegnanti e amministratori potrebbero essere ottime scelte per un componente aggiuntivo di Classroom.

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

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

• Nella sezione Risorse grafiche:

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

  • Gli screenshot forniti sono rappresentazioni accurate della tua esperienza relativa al componente aggiuntivo.

• In Link per 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 nella tua scheda fai riferimento a qualsiasi prodotto Google, utilizza il nome nel formato fornito nell'elenco dei marchi. Assicurati di includere il simbolo del marchio (TM), se specificato; utilizza "Google DocsTM" e non "Documenti Google".

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

Se vuoi consentire l'integrazione delle tue applicazioni Google Workspace Marketplace con i servizi di licenze 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 è pensata per promuovere nessuno dei due tipi di installazione. Puoi scegliere se consentire l'installazione individuale nella pagina Configurazione app dell'SDK di Google Workspace Marketplace.

Installazione come amministratore

Le installazioni per amministratori consentono agli amministratori 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 l'installazione da parte dell'amministratore. Facoltativamente, l'amministratore può concedere il consenso a tutti gli ambiti di accesso per conto di tutti gli utenti nel dominio; agli utenti non viene richiesto di acconsentire a nessun ambito di accesso se l'amministratore sceglie di farlo.

Di seguito sono riportate alcune considerazioni relative all'installazione da parte degli amministratori.

• 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, il canale delle installazioni tramite un amministratore potrebbe contribuire a garantire che le licenze vengano distribuite e utilizzate in modo appropriato con l'istituto corrispondente.
• Meno carico per gli utenti finali. L'installazione da parte di un amministratore riduce il carico della configurazione per insegnanti e studenti. Ciò può comportare un'esperienza utente più fluida, con meno clic e meno opportunità di confusione.

Vedi Installare le app del Marketplace nel dominio per ulteriori informazioni su come eseguire installazioni da parte degli amministratori 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. All'utente viene richiesto di concedere il consenso agli ambiti di accesso del componente aggiuntivo durante l'installazione.

Di seguito sono riportate alcune considerazioni relative alla singola installazione.

• Favorire l'adozione. Più utenti possono vedere e installare il tuo componente aggiuntivo da Google Workspace Marketplace. Consentire l'installazione individuale può indurre un maggior numero di insegnanti ad adottare o sostenere il tuo prodotto.
• Test per gli amministratori. 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 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 visualizzarne la scheda in Google Workspace Marketplace ma non possono installarlo. Viene visualizzato 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 inserite nella lista consentita.

Per saperne di più, 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 dell'allegato. Questo URL viene utilizzato come valore src 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.

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

Consulta la pagina della guida relativa agli iframe per ulteriori dettagli su questi campi.

Account di prova

Crea account di prova sul tuo dominio demo per verificare il corretto comportamento del componente aggiuntivo privato. Sono necessari due account studente per verificare il passaggio da uno studente all'altro nell'iframe della revisione del lavoro dello studente.

Account di prova suggeriti:

• Insegnante Tammy, tammy.teacher@<dominio demo>
• Samuele Studente, sam.student@<il tuo dominio demo>
• Sally Studente, sally.student@<dominio demo>

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 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 la Figura 2).
4. Inserisci i membri e i proprietari del gruppo.

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