Gli insegnanti che sfruttano sia Classroom che strumenti di terze parti devono affrontare la sfida di configurare i propri corsi e gli elenchi degli studenti su più piattaforme. Questa operazione può essere eseguita manualmente, utilizzando caricamenti CSV o inserendo le email una alla volta. Con l'API Classroom, tuttavia, gli strumenti di terze parti possono ridurre i carichi di lavoro degli insegnanti integrandosi con il caso d'uso più comune dell'API: importazione dell'elenco degli studenti.
L'importazione dell'elenco degli studenti consente alle piattaforme di terze parti di recuperare i metadati, gli insegnanti e gli studenti di un corso corso per corso, con autorizzazioni dell'insegnante o dell'amministratore. Gli insegnanti possono recuperare i dettagli dei corsi che insegnano, mentre gli amministratori hanno accesso ai dettagli di tutti i corsi di un intero dominio. Questa flessibilità consente agli sviluppatori di integrare agevolmente gli elenchi degli studenti di Classroom sulla loro piattaforma sia a livello di singolo insegnante che su tutto il dominio utilizzando le credenziali di amministratore.
Prima di approfondire i dettagli tecnici di un'integrazione per l'importazione dell'elenco degli studenti, vediamo un flusso di lavoro di esempio:
Nell'applicazione di terze parti, un insegnante sceglie l'opzione per importare un corso di Classroom.
L'applicazione di terze parti chiama il metodo
courses.listtramite l'API Classroom, che restituisce un JSON di risposta con tutti i corsi dell'insegnante.Dalla risposta JSON, l'applicazione di terze parti mostra i titoli dei corsi dell'insegnante per consentire loro di selezionarne uno. La richiesta dovrà tenere traccia degli ID del corso per procedere con il passaggio successivo.
Con l'ID corso selezionato, l'applicazione di terze parti chiama i metodi
students.listeteachers.liste visualizza sul proprio sito web tutti i nomi per consentire agli insegnanti di confermare l'importazione.Utilizzando le email restituite nei file JSON di risposta
students.listeteachers.list, l'applicazione di terze parti invita gli utenti a partecipare al corso appena importato sulla propria piattaforma.
Per ognuno dei metodi menzionati nel flusso di lavoro, puoi utilizzare Explorer API per vedere esattamente il comportamento di ogni metodo. Prima di completare questa guida, ti consigliamo inoltre di attenerti ai seguenti suggerimenti:
Per iniziare
Prima di implementare le specifiche dell'importazione dell'elenco degli studenti di Classroom, devi determinare quali informazioni sul corso e sugli utenti dovrai recuperare tramite l'API. Puoi vedere quali metadati dei corsi sono disponibili nella documentazione di riferimento, ma alcuni campi obbligatori o comuni necessari possono essere riepilogati di seguito:
| Campo | Utilizzo |
|---|---|
| id | Obbligatorio per le richieste API di recupero di studenti o insegnanti |
| nome | Consigliato per facilità d'uso da parte dell'utente, ovvero visualizzazione sul tuo sito web |
| ownerId | Necessaria durante l'importazione a livello di dominio per identificare correttamente l'insegnante principale di un corso |
Le informazioni di questo corso vengono recuperate nel passaggio courses.list del flusso di lavoro riportato sopra. In questa richiesta puoi specificare determinati parametri. Sebbene non siano obbligatori per questo metodo, alcuni parametri consigliati sono:
| Parametro | Utilizzo |
|---|---|
| courseState | Se non specificata, l'API restituirà i corsi di tutti e sei gli stati dei corsi. Ti consigliamo di specificare ACTIVE per recuperare i corsi attualmente utilizzati dagli insegnanti. |
| pageSize | Per gli insegnanti che importano i propri corsi, consigliamo di specificare un valore pageSize piccolo (meno di 10) per ridurre i tempi di risposta della chiamata API. |
| pageToken | Obbligatorio se utilizzi richieste impaginate. |
| teacherId | Consigliato perché gli amministratori di dominio spesso tengono corsi. Se non specificata, la richiesta restituirà corsi per gli insegnanti nell'intero dominio. |
| campi | Suggerito per ridurre il tempo di risposta della chiamata API. |
Utilizzando gli ID corso recuperati in precedenza, l'applicazione ora può recuperare l'elenco di studenti e co-insegnanti per il corso o il corso in questione. Questo ID corso è l'unico parametro di query obbligatorio per teachers.list e students.list, ma allo stesso modo consigliamo di specificare i parametri pageSize e fields per ridurre il tempo di risposta delle chiamate API.
Tutti i campi disponibili per le risorse per studenti e insegnanti sono disponibili nella rispettiva documentazione. I due campi maggiormente utilizzati e generalmente obbligatori sono quelli del campo profile: profile.name e profile.emailAddress.
| Campo | Utilizzo |
|---|---|
| profile.name | Consigliato per facilità d'uso da parte dell'utente, ovvero visualizzazione sul tuo sito web |
| profile.emailAddress | Obbligatorio per le applicazioni che cercano di identificare in modo univoco gli studenti |
Per recuperare e utilizzare i dettagli del corso o dell'elenco degli studenti da Classroom, la tua applicazione dovrà richiedere l'autorizzazione agli utenti. Esistono tre (3) ambiti obbligatori per implementare questo flusso di lavoro:
- https://www.googleapis.com/auth/classroom.courses.readonly
- Fornisce l'accesso in sola lettura ai corsi di Google Classroom
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Fornisce l'accesso in sola lettura ai redatori dei corsi di Google Classroom (insegnanti e studenti)
- https://www.googleapis.com/auth/classroom.profile.emails
- Fornisce l'accesso in lettura alla proprietà email di insegnanti e studenti
Sincronizza gli elenchi degli studenti con le notifiche Pub/Sub
Nel corso dell'anno scolastico, gli elenchi potrebbero cambiare man mano che gli studenti abbandonano o aggiungono un corso. L'aggiunta di notifiche Pub/Sub ti consentirà di mantenere sincronizzata l'applicazione di terze parti con i registri di Classroom. Per ricevere le notifiche, devi configurare un argomento Google Cloud Pub/Sub e poi registrarlo con l'API Classroom. Questa registrazione è una richiesta a Classroom di inviare dati dal feed fornito all'argomento in questione. Questo feed sarà l'evento che attiva la nuova sincronizzazione con l'elenco degli studenti di Classroom di un insegnante.
L'utilizzo delle notifiche push richiede un ambito aggiuntivo, che non deve essere inviato per la verifica:
- https://www.googleapis.com/auth/classroom.push-notifications
- Consente all'app di registrarsi per qualsiasi attività di notifiche push
Per ulteriori dettagli sull'integrazione con le notifiche push di Classroom, consulta la nostra guida alla gestione delle notifiche push.