Gli insegnanti che utilizzano sia Classroom sia strumenti di terze parti devono affrontare la sfida della configurazione dei corsi e degli elenchi degli studenti su più piattaforme. Questa operazione può essere eseguita manualmente, tramite il caricamento di file CSV o inserendo le email una alla volta. Con l'API Classroom, tuttavia, gli strumenti di terze parti possono ridurre il carico di lavoro degli insegnanti integrandoli con il caso d'uso più comune dell'API: l'importazione degli elenchi degli studenti.
L'importazione degli elenchi degli studenti consente alle piattaforme di terze parti di recuperare i metadati, gli insegnanti e gli studenti di un corso a livello di singolo corso avvalendosi delle autorizzazioni degli insegnanti o degli amministratori. 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 facilmente i registri di Classroom nella propria piattaforma sia a livello di singolo insegnante sia in un intero dominio utilizzando le credenziali di amministratore.
Prima di esaminare i dettagli tecnici di come potrebbe essere un'integrazione di importazione del roster, diamo un'occhiata a 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 restituirà 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, da cui può selezionarne uno. L'applicazione dovrà tenere traccia degli ID corso per passare al passaggio successivo.
Con l'ID corso selezionato, l'applicazione di terze parti chiama i metodi
students.listeteachers.liste mostra tutti i nomi sul proprio sito web 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 ciascuno dei metodi menzionati nel flusso di lavoro, puoi utilizzare API Explorer per vedere esattamente il comportamento di ciascun metodo. Prima di terminare la guida, ti consigliamo inoltre di fare quanto segue:
Per iniziare
Prima di implementare le specifiche dell'importazione dell'elenco di Classroom, devi determinare quali informazioni su corsi e utenti devi recuperare tramite l'API. Puoi vedere quali metadati dei corsi sono disponibili nella documentazione di riferimento, ma alcuni campi obbligatori o comuni possono essere riassunti di seguito:
| Campo | Utilizza |
|---|---|
| id | Obbligatorio per le richieste API che recuperano studenti o insegnanti |
| nome | Consigliato per la facilità d'uso da parte dell'utente, ad esempio la visualizzazione sul tuo sito web |
| ownerId | Obbligatoria quando effettui un'importazione a livello di dominio per identificare correttamente l'insegnante principale di un corso |
Queste informazioni sul corso vengono recuperate nel passaggio courses.list del flusso di lavoro riportato sopra. In questa richiesta puoi specificare determinati parametri di richiesta. Anche se nessuno è obbligatorio per questo metodo, alcuni parametri consigliati sono:
| Parametro | Utilizza |
|---|---|
| courseState | Se non viene specificato, l'API restituirà i corsi di tutti e sei gli stati. Ti consigliamo di specificare ACTIVE per recuperare i corsi attualmente in uso dagli insegnanti. |
| pageSize | Per gli insegnanti che importano i propri corsi, consigliamo di specificare un valore pageSize ridotto (meno di 10) per ridurre il tempo di risposta della chiamata API. |
| pageToken | Obbligatorio se utilizzi richieste paginate. |
| teacherId | Consigliato perché gli amministratori di dominio spesso insegnano i corsi. Se non viene specificato, la richiesta restituirà i corsi per gli insegnanti dell'intero dominio. |
| campi | Consigliato 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 i corsi in questione. Questo ID corso è
l'unico parametro di query obbligatorio per teachers.list e students.list, ma
potresti anche prendere in considerazione la possibilità 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 più utilizzati e in genere obbligatori sono nel campo profile: profile.name e profile.emailAddress.
| Campo | Utilizza |
|---|---|
| profile.name | Consigliato per la facilità d'uso da parte dell'utente, ad esempio la visualizzazione sul tuo sito web |
| profile.emailAddress | Obbligatorio per le applicazioni che vogliono identificare in modo univoco gli studenti |
Per recuperare e utilizzare questi dettagli dei corsi o degli elenchi degli studenti da Classroom, la tua app dovrà richiedere l'autorizzazione agli utenti. Sono necessari tre (3) ambiti per implementare questo flusso di lavoro:
- https://www.googleapis.com/auth/classroom.courses.readonly
- Fornisce l'accesso di sola lettura ai corsi di Google Classroom
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Fornisce l'accesso di sola lettura agli elenchi degli studenti 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
Sincronizzare i ruoli con le notifiche Pub/Sub
Man mano che l'anno scolastico procede, gli elenchi potrebbero cambiare man mano che gli studenti abbandonano o aggiungono corsi. L'aggiunta di notifiche Pub/Sub ti consentirà di mantenere la tua applicazione di terze parti sincronizzata con i rostri di Classroom. Per ricevere notifiche, devi configurare un argomento Google Cloud Pub/Sub e poi registrarlo con l'API Classroom. Questa registrazione è una richiesta a Classroom di inviare i dati dal feed specificato all'argomento specificato. Questo feed sarà l'attivatore di eventi per 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 notifica push
Per ulteriori dettagli su come eseguire l'integrazione con le notifiche push di Classroom, consulta la nostra guida alla gestione delle notifiche push.