Presentazione

Gli insegnanti che utilizzano sia Classroom sia 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, tramite l'utilizzo di caricamenti 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 integrandosi con il caso d'uso più comune dell'API: l'importazione degli elenchi.

L'importazione dell'elenco degli studenti consente alle piattaforme di terze parti di recuperare i metadati, gli insegnanti e gli studenti di un corso in base al corso con autorizzazioni di insegnante o 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 facilmente gli elenchi di Classroom nella loro piattaforma a livello di singolo insegnante o in un intero dominio utilizzando le credenziali di amministratore.

Gli amministratori di dominio potrebbero utilizzare strumenti di terze parti come insegnanti dei propri corsi. Quando recuperi i dettagli del corso tramite l'API, è necessario gestire con attenzione la differenza tra le autorizzazioni di amministratore di dominio e insegnante.

Prima di esaminare i dettagli tecnici di come potrebbe apparire un'integrazione di importazione degli elenchi, rivediamo un esempio di flusso di lavoro:

1. Nell'applicazione di terze parti, un insegnante sceglie l'opzione per importare un corso di Classroom.

2. L'applicazione di terze parti chiama il metodo courses.list tramite l'API Classroom, che restituirà una risposta JSON con tutti i corsi dell'insegnante.

3. Dalla risposta JSON, l'applicazione di terze parti mostra i titoli dei corsi dell'insegnante, in modo che possa selezionarne uno. L'applicazione dovrà tenere traccia degli ID corso per continuare con il passaggio successivo.

4. Con l'ID corso selezionato, l'applicazione di terze parti chiama i metodi students.list e teachers.list e mostra tutti i nomi sul suo sito web affinché gli insegnanti confermino l'importazione.

5. Utilizzando le email restituite nei file JSON di risposta students.list e teachers.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 l'API Explorer per vedere esattamente come si comporta ogni metodo. Prima di terminare questa guida, ti consigliamo anche di leggere i seguenti articoli:

1. Gestire i corsi con l'API Classroom
2. Gestire studenti e insegnanti

Oltre al diagramma del flusso di lavoro riportato di seguito, consulta l'esempio pratico di ActivelyLearn per comprendere meglio questo tipo di integrazione.

Per iniziare

Prima di implementare i dettagli dell'importazione dell'elenco di Classroom, devi determinare quali informazioni su corsi e utenti devi recuperare tramite l'API. Puoi vedere quali metadati del corso sono disponibili nella documentazione di riferimento, ma alcuni campi obbligatori o comuni necessari possono essere riepilogati di seguito:

Campo	Utilizza
id	Obbligatorio per le richieste API che recuperano studenti o insegnanti
nome	Consigliato per la facilità d'uso per l'utente, ad esempio la visualizzazione sul tuo sito web
ownerId	Obbligatorio quando l'importazione viene eseguita a livello di dominio per identificare correttamente l'insegnante principale di un corso

Queste informazioni sul corso vengono recuperate al passaggio courses.list del flusso di lavoro sopra. In questa richiesta puoi specificare determinati parametri. Sebbene nessuno sia obbligatorio per questo metodo, alcuni parametri consigliati sono:

Parametro	Utilizza
courseState	Se non specificato, l'API restituirà i corsi di tutti e sei gli stati del corso. 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 ridotto (inferiore a 10) per ridurre il tempo di risposta della chiamata API.
pageToken	Obbligatorio se utilizzi richieste suddivise in pagine.
teacherId	Consigliato perché gli amministratori di dominio spesso insegnano corsi. Se non viene specificato, la richiesta restituirà i corsi per gli insegnanti dell'intero dominio.
i campi	Consigliato per ridurre il tempo di risposta della chiamata API.

Utilizzando gli ID corso recuperati in precedenza, la tua applicazione può ora recuperare l'elenco di studenti e co-insegnanti per quel corso o quei corsi. Questo ID corso è l'unico parametro di query obbligatorio per teachers.list e students.list, ma potresti anche prendere in considerazione la specifica dei parametri pageSize e fields per ridurre il tempo di risposta delle chiamate API.

Tutti i campi disponibili per le risorse studente e insegnante sono disponibili nella rispettiva documentazione. I due campi più comunemente utilizzati e in genere obbligatori si trovano nel campo profile: profile.name e profile.emailAddress.

Campo	Utilizza
profile.name	Consigliato per la facilità d'uso per l'utente, ad esempio la visualizzazione sul tuo sito web
profile.emailAddress	Obbligatorio per le applicazioni che cercano di identificare in modo univoco gli studenti

Per recuperare e utilizzare uno qualsiasi di questi dettagli del corso o dell'elenco da Classroom, la tua applicazione dovrà richiedere l'autorizzazione agli utenti. Per implementare questo flusso di lavoro sono necessari tre (3) ambiti:

• 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 in sola lettura agli elenchi 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

Poiché uno di questi ambiti è considerato sensibile, la tua applicazione dovrà completare una procedura di verifica.

Sincronizzare gli elenchi con le notifiche Pub/Sub

Con l'avanzare dell'anno scolastico, gli elenchi potrebbero cambiare man mano che gli studenti abbandonano o aggiungono corsi. L'aggiunta di notifiche Pub/Sub ti consentirà di mantenere sincronizzata la tua applicazione di terze parti con i registri di Classroom. Per ricevere le notifiche, devi configurare un argomento Google Cloud Pub/Sub e registrarlo con l'API Classroom. Questa registrazione è una richiesta a Classroom di inviare i dati del feed specificato all'argomento specificato. Questo feed sarà l'attivatore di eventi per la risincronizzazione con l'elenco degli studenti di un insegnante in Classroom.

A seconda del caso d'uso della tua applicazione, puoi iscriverti alle notifiche in base al corso o al dominio.

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.