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 la utilizzano di iscriversi per ricevere notifiche quando i dati cambiano in Classroom. Le notifiche vengono consegnate a un argomento Cloud Pub/Sub, in genere entro pochi minuti dalla 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 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ò registrarsi. Ad esempio, "modifiche all'elenco degli studenti per il corso 1234".
  • Una registrazione è un'istruzione all'API Classroom per inviare notifiche da un determinato feed a una destinazione.

Una volta creata la registrazione di un feed, l'argomento Cloud Pub/Sub della registrazione riceve le notifiche dal 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

Al momento l'API Classroom offre tre tipi di feed:

  • Ogni dominio ha un feed Modifiche all'elenco per dominio, che mostra notifiche quando studenti e insegnanti si iscrivono e lasciano i corsi nel dominio.
  • Ogni corso ha un feed Modifiche all'elenco degli studenti per il corso, che mostra notifiche quando studenti e insegnanti si iscrivono e lasciano il corso.
  • Ogni corso ha un feed modifiche ai lavori del corso per il corso, che mostra le notifiche quando gli oggetti dei lavori del corso o i compiti inviati dagli studenti vengono creati o modificati nel corso.

Configurazione di un argomento Cloud Pub/Sub

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

Per configurare un argomento Cloud Pub/Sub, devi eseguire i seguenti passaggi:

  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 (la soluzione 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 argomento per ricevere tutte le notifiche ti assicura 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 di notifiche push (classroom-notifications@system.gserviceaccount.com) l'autorizzazione a pubblicare nel tuo argomento.

NOTA: se concedi all'account di servizio Push Notifications l'autorizzazione per pubblicare nel tuo argomento Cloud Pub/Sub, gli utenti che possono effettuare richieste dal progetto della console per gli sviluppatori potranno stabilire che esiste e registrarsi per ricevere notifiche. Molte applicazioni memorizzano gli ID client OAuth sul lato client, quindi gli utenti finali potrebbero essere in grado di effettuare richieste dal progetto della Developer Console. Se la situazione ti riguarda e temi 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 per le notifiche push da un altro progetto Play Console.

Registra la tua applicazione per ricevere le notifiche

Dopo aver creato un argomento in cui l'account di servizio per le notifiche push dell'API Classroom può pubblicare, puoi registrarti per ricevere le notifiche utilizzando il metodo registrations.create(). Il metodo registrations.create() convalida che l'argomento Cloud Pub/Sub fornito possa essere raggiunto dall'account di servizio per le notifiche push. Il metodo non va a buon fine se l'account di servizio delle notifiche push non può raggiungere l'argomento; ad esempio, se l'argomento non esiste o non gli hai concesso l'autorizzazione di pubblicazione per l'argomento.

Autorizzazione

Come per 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 Notifiche push (https://www.googleapis.com/auth/classroom.push-notifications) e tutti gli ambiti necessari per visualizzare i dati sulle notifiche inviate.

  • Per i feed di variazioni al roster, si intende l'ambito Roster 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, si tratta delle versioni "studenti" dell'ambito del lavoro del corso o (idealmente) della relativa 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 una concessione OAuth dall'utente autorizzato con gli ambiti richiesti. Se l'utente scollega l'applicazione, le notifiche vengono interrotte. Tieni presente che al momento la delega dell'autorità a livello di dominio non è supportata per questo scopo. Se provi a registrarti per ricevere le notifiche utilizzando solo l'autorità delegata a livello di dominio, riceverai un errore @MissingGrant.

Ricezione di notifiche.

Le notifiche sono codificate in JSON e contengono:

  • Il nome della raccolta contenente la risorsa modificata. Per le notifiche relative alle modifiche al roster, il valore è courses.students o courses.teachers. Per le modifiche dei lavori del corso, è courses.courseWork o courses.courseWork.studentSubmissions.
  • Identificatori in una mappa per la risorsa che è stata modificata. Questa mappa è progettata per associare gli argomenti al 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 invariati 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 invariati a courses.courseWork.get() e le modifiche alla raccolta courses.courseWork.studentSubmissions avranno i campi courseId, courseWorkId e id che possono essere inviati invariati 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, contenente l'identificatore della registrazione che ha causato la notifica, che può essere utilizzato con registrations.delete() per annullare la registrazione dalle notifiche.