Notifiche push nell'API Classroom

Puoi utilizzare i metodi della raccolta Registrations 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 iscriversi per ricevere notifiche quando i dati cambiano in Classroom. Le notifiche vengono inviate a un argomento Cloud Pub/Sub, in genere pochi minuti dopo la modifica.

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

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ò iscriversi. Ad esempio, "modifiche all'elenco del corso 1234".
• Una registrazione è un'istruzione per l'API Classroom per inviare notifiche da un feed specifico 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 inviando una richiesta identica a registrations.create().

L'argomento Cloud Pub/Sub riceve notifiche solo sulle 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 per il dominio, che mostra le notifiche quando studenti e insegnanti partecipano e abbandonano i corsi in quel dominio.
• Ogni corso ha un feed Modifiche all'elenco del corso, che mostra le notifiche quando studenti e insegnanti si uniscono ai corsi e li abbandonano.
• Ogni corso ha un feed Modifiche ai lavori del corso per il corso, che mostra le notifiche quando vengono creati o modificati lavori del corso o invii degli studenti in quel corso.

Nota: siamo a conoscenza di un problema per cui le notifiche non vengono inviate per le modifiche ai corsi in cui il proprietario del corso non fa parte di un dominio Google Workspace for Education. Se lavori con corsi non collegati a un dominio Google Workspace for Education, tieni presente che le notifiche per il COURSE_ROSTER_CHANGES feedType potrebbero non funzionare.

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:

1. Assicurati di soddisfare i prerequisiti di Cloud Pub/Sub.
2. Configura un client Cloud Pub/Sub.
3. Esamina i prezzi di Cloud Pub/Sub e attiva la fatturazione per il tuo progetto Developer Console.

4. Crea 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.

5. Crea una sottoscrizione in Cloud Pub/Sub per indicare a Cloud Pub/Sub come inviare le notifiche.

6. Infine, prima di registrarti per le notifiche push, devi concedere all'account di servizio delle notifiche push ([e-mail]) l'autorizzazione per pubblicare nell'argomento.

Nota: se concedi al service account delle notifiche push l'autorizzazione a pubblicare nell'argomento Cloud Pub/Sub, gli utenti che possono effettuare richieste dal tuo progetto Developer Console potranno determinare che esiste e registrarsi per ricevere notifiche. Molte applicazioni memorizzano gli ID client OAuth lato client, pertanto gli utenti finali potrebbero essere in grado di effettuare richieste dal tuo progetto Developer Console. Se questo è il tuo caso e ti preoccupa che gli utenti finali inviino notifiche indesiderate al tuo argomento Cloud Pub/Sub o che conoscano i nomi degli argomenti Cloud Pub/Sub che utilizzi per le notifiche push, ti consigliamo di registrarti alle notifiche push da un progetto Developer Console diverso.

Registrare l'applicazione per le notifiche

Una volta che hai un argomento a cui l'account di servizio di notifiche push dell'API Classroom può pubblicare, puoi registrarti per ricevere le notifiche utilizzando il metodo registrations.create(). Il metodo registrations.create() verifica che l'argomento Cloud Pub/Sub fornito sia raggiungibile dall'account di servizio delle notifiche push. Il metodo non va a buon fine se l'account di servizio di notifica push non riesce a raggiungere l'argomento, ad esempio se l'argomento non esiste o se non gli 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 su cui vengono inviate le notifiche.

• Per i feed di modifica degli elenchi, questo significa l'ambito Elenchi o (idealmente) la relativa variante di sola lettura (https://www.googleapis.com/auth/classroom.rosters.readonly o https://www.googleapis.com/auth/classroom.rosters).
• Per i feed delle modifiche ai lavori del corso, ciò 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).

Per la ricezione delle notifiche, l'applicazione deve conservare una concessione OAuth dell'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 provi a registrarti per ricevere notifiche utilizzando solo l'autorità delegata a livello di dominio, riceverai un errore @MissingGrant.

Ricevere notifiche

Le notifiche sono codificate in formato JSON e contengono:

• Il nome della raccolta contenente la risorsa modificata. Per le notifiche relative alle modifiche all'elenco, questo valore è courses.students o courses.teachers. Per le modifiche al lavoro del corso, questo valore è courses.courseWork o courses.courseWork.studentSubmissions.
• 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, 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 i campi courseId e id che possono essere inviati senza modifiche a courses.courseWork.get() e le modifiche alla raccolta courses.courseWork.studentSubmissions avranno i 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 di messaggio registrationId, contenente l'identificatore della registrazione che ha causato la notifica, che può essere utilizzato con registrations.delete() per annullare la registrazione alle notifiche.