Notifiche push nell'API Classroom

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

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

Panoramica delle notifiche push di Classroom

Le notifiche push dell'API Classroom consentono alle applicazioni che utilizzano l'API Classroom di iscriversi per ricevere le 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 le 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ò iscriversi. Ad esempio, "cambi dell'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 una registrazione per un feed, l'argomento Cloud Pub/Sub della registrazione riceverà le notifiche da quel feed fino alla scadenza. La registrazione dura una settimana, ma puoi estenderla in qualsiasi momento prima che scada inviando una richiesta identica a registrations.create().

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

Tipi di feed

L'API Classroom attualmente offre tre tipi di feed:

  • Ogni dominio ha un feed di modifiche dell'elenco degli studenti per il dominio, che mostra notifiche quando studenti e insegnanti entrano a far parte di un corso e lo abbandonano.
  • Ogni corso ha un feed di modifiche dell'elenco degli studenti del corso, che mostra notifiche quando studenti e insegnanti entrano a far parte di un corso e lo abbandonano.
  • Ogni corso dispone di un feed per le modifiche al lavoro del corso che espone notifiche quando qualsiasi lavoro del corso o oggetto dell'invio degli studenti viene creato o modificato in quel corso.

Configurazione di un argomento Cloud Pub/Sub

Le notifiche vengono consegnate 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, procedi nel seguente modo:

  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 abilita la fatturazione per il tuo progetto della Developer Console.

  4. Crea un argomento Cloud Pub/Sub nella console per gli sviluppatori (il più semplice), tramite lo strumento a riga di comando (per l'uso programmatico semplice) o utilizzando l'API Cloud Pub/Sub. Tieni presente che Cloud Pub/Sub consente solo un numero limitato di argomenti, quindi utilizzare 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 l'autorizzazione all'account di servizio per le notifiche push (classroom-notifications@system.gserviceaccount.com) per pubblicare nell'argomento.

NOTA: se concedi all'account di servizio per le notifiche push l'autorizzazione a pubblicare nell'argomento Cloud Pub/Sub, gli utenti che possono effettuare richieste dal tuo progetto della Console per gli sviluppatori potranno verificarne l'esistenza 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 questo è il tuo caso e temi che gli utenti finali inviino notifiche indesiderate al tuo argomento Cloud Pub/Sub o conoscano i nomi degli argomenti Cloud Pub/Sub che utilizzi per le notifiche push, dovresti considerare la registrazione per le notifiche push da un altro progetto della Developer Console.

Registra la tua applicazione per le notifiche

Quando disponi di un argomento in cui l'account del servizio di 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 delle 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 hai concesso l'autorizzazione di pubblicazione per l'argomento in questione.

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 gli eventuali ambiti necessari per visualizzare i dati relativi alle notifiche inviate.

  • Per i feed di modifica degli elenchi degli studenti, ciò significa l'ambito degli 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 delle modifiche al lavoro del corso, si tratta delle versioni "studenti" dell'ambito dei lavori del corso o, possibilmente, della 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 recapitate, 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 a questo scopo. Se tenti di registrarti per le notifiche utilizzando solo l'autorità delegata a livello di dominio, riceverai un errore @MissingGrant.

Ricezione di notifiche

Le notifiche sono codificate con JSON e contengono:

  • Il nome della raccolta contenente la risorsa modificata. Per le notifiche sulle modifiche dell'elenco degli studenti, può essere courses.students o courses.teachers. Per le modifiche ai lavori del corso, può essere courses.courseWork o courses.courseWork.studentSubmissions.
  • Identificatori della risorsa che è stata modificata in una mappa. Questa mappa è progettata per abbinare gli argomenti al metodo get della risorsa appropriata. Per le notifiche sulle 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 Corsi.courseWork avranno courseId e id campi che potranno essere inviati senza modifiche a courses.courseWork.get() e courseWorkIdal campo selezionato.courseIdidcourses.courseWork.studentSubmissions.get()

Lo snippet di codice riportato di seguito illustra 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 alle notifiche.