I componenti aggiuntivi di Google Classroom sono ora in disponibilità generale per gli sviluppatori. Per ulteriori informazioni, consulta la documentazione relativa ai componenti aggiuntivi.

Notifiche push nell'API Classroom

Puoi utilizzare i metodi della Registrations raccolta per ricevere notifiche quando i dati cambiano in Classroom.

Questo articolo fornisce una panoramica concettuale e semplici istruzioni su come iniziare a ricevere notifiche push.

Panoramica delle notifiche push di Classroom

La funzionalità di notifiche push dell'API Classroom consente alle applicazioni che utilizzano l'API Classroom di abbonarsi alle notifiche quando i dati cambiano in Classroom. Le notifiche vengono inviate a un argomento Cloud Pub/Sub, in genere entro pochi minuti da la modifica.

Per ricevere notifiche push, devi configurare un argomento Cloud Pub/Sub topic e fornire il nome dell'argomento quando crei una registrazione per il feed di notifiche appropriato.

Di seguito sono riportate le definizioni dei concetti chiave utilizzati in questa documentazione:

Una destinazione è un luogo in cui vengono inviate le notifiche.
Un feed è un tipo di notifiche a cui un'applicazione di terze parti può abbonarsi. Ad esempio, "modifiche all'elenco degli studenti per il corso 1234".
Una registrazione è un'istruzione all'API Classroom per inviare le notifiche da un determinato feed a una destinazione.

Una volta creata una registrazione per un feed, l'argomento Cloud Pub/Sub della registrazione riceve le notifiche da quel feed fino alla scadenza. La registrazione dura una settimana, ma puoi estenderla in qualsiasi momento prima della scadenza effettuando una richiesta identica a registrations.create().

L'argomento Cloud Pub/Sub riceve solo le notifiche relative alle risorse che puoi visualizzare con le credenziali fornite durante la creazione di una registrazione. Ad esempio, se l'utente revoca l'autorizzazione alla tua applicazione o viene rimosso come insegnante, le notifiche non vengono più inviate.

Tipi di feed

L'API Classroom offre tre tipi di feed:

Ogni dominio ha un feed modifiche all'elenco degli studenti per il dominio, che espone le notifiche quando studenti e insegnanti partecipano e abbandonano i corsi in quel dominio.
Ogni corso ha un feed modifiche all'elenco degli studenti per il corso, che espone le notifiche quando studenti e insegnanti partecipano e abbandonano i corsi in quel corso.
Ogni corso ha un feed modifiche ai lavori del corso per il corso, che espone le notifiche quando vengono creati o modificati oggetti di lavori del corso o di compiti inviati dagli studenti in quel corso.

Configurare un argomento Cloud Pub/Sub

Le notifiche vengono inviate agli argomenti Cloud Pub/Sub. Da Cloud Pub/Sub, puoi ricevere notifiche su un webhook o eseguendo il polling di un endpoint di sottoscrizione.

Per configurare un argomento Cloud Pub/Sub, devi:

Assicurarti di soddisfare i prerequisiti di Cloud Pub/Sub.
Configurare un client Cloud Pub/Sub.
Esaminare i prezzi di Cloud Pub/Sub, e attivare la fatturazione per il progetto della console per sviluppatori.
Creare un argomento Cloud Pub/Sub nella console per sviluppatori (il modo più semplice), tramite lo strumento a riga di comando (per un semplice utilizzo programmatico) o utilizzando l'API Cloud Pub/Sub. Tieni presente che Cloud Pub/Sub consente solo un numero limitato di argomenti, quindi l'utilizzo di un solo argomento per ricevere tutte le notifiche ti garantisce di non riscontrare problemi di scalabilità se la tua applicazione diventa popolare.
Creare un abbonamento in Cloud Pub/Sub per indicare a Cloud Pub/Sub come inviare le notifiche.
Infine, prima di registrarti per le notifiche push, devi concedere all'account di servizio delle notifiche push (classroom-notifications@system.gserviceaccount.com) l'autorizzazione a pubblicare nel tuo argomento.

Registrare l'applicazione per le notifiche

Una volta che hai un argomento in cui l'account di servizio delle notifiche push dell'API Classroom può pubblicare, puoi registrarti per ricevere le notifiche utilizzando il registrations.create() metodo. Il metodo registrations.create() verifica che l'account di servizio delle notifiche push possa raggiungere l'argomento Cloud Pub/Sub fornito. Il metodo non riesce se l'account di servizio delle notifiche push non riesce a raggiungere l'argomento, ad esempio se l'argomento non esiste o se non hai concesso l'autorizzazione di pubblicazione per quell'argomento.

Autorizzazione

Come tutte le chiamate all'API Classroom, le chiamate a registrations.create() devono essere autorizzate con un token di autorizzazione. Questo token di autenticazione deve includere l'ambito delle notifiche push (https://www.googleapis.com/auth/classroom.push-notifications) e tutti gli ambiti necessari per visualizzare i dati relativi alle notifiche inviate.

Per i feed di modifiche all'elenco degli studenti, questo significa l'ambito Elenchi degli studenti o (idealmente) la sua variante di sola lettura (https://www.googleapis.com/auth/classroom.rosters.readonly o https://www.googleapis.com/auth/classroom.rosters).
Per i feed di modifiche ai lavori del corso, questo significa le versioni "studenti" dell'ambito dei lavori del corso o (idealmente) la sua variante di sola lettura (https://www.googleapis.com/auth/classroom.coursework.students.readonly o https://www.googleapis.com/auth/classroom.coursework.students).

Affinché le notifiche vengano inviate, l'applicazione deve conservare un'autorizzazione con OAuth dall'utente autorizzato con gli ambiti richiesti. Se l'utente disconnette l'applicazione, le notifiche cessano. Tieni presente che al momento la delega dell'autorità a livello di dominio non è supportata per questo scopo. Se tenti di registrarti per ricevere le notifiche utilizzando solo l'autorità delegata a livello di dominio, riceverai un errore @MissingGrant.

Ricevere notifiche

Le notifiche sono codificate con JSON e contengono:

Il nome della raccolta contenente la risorsa modificata. Per le notifiche relative alle modifiche all'elenco degli studenti, si tratta di courses.students o courses.teachers. Per le modifiche ai lavori del corso, si tratta di courses.courseWork o courses.courseWork.studentSubmissions.
Gli identificatori della risorsa modificata, in una mappa. Questa mappa è progettata per corrispondere agli argomenti del metodo get della risorsa appropriata. Per le notifiche relative alle modifiche all'elenco degli studenti, i campi courseId e userId verranno compilati e potranno essere inviati senza modifiche a courses.students.get() o courses.teachers.get(). Allo stesso modo, le modifiche alla raccolta courses.courseWork avranno campi courseId e id che possono essere inviati senza modifiche a courses.courseWork.get() e le modifiche alla raccolta courses.courseWork.studentSubmissions avranno campi courseId, courseWorkId e id che possono essere inviati senza modifiche a courses.courseWork.studentSubmissions.get().

Il seguente snippet di codice mostra una notifica di esempio:

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

Le notifiche hanno anche un attributo del messaggio registrationId, che contiene l' identificatore della registrazione che ha causato la notifica e che può essere utilizzato con registrations.delete() per annullare la registrazione alle notifiche.