Struttura dell'API

Questa guida fornisce una panoramica dei componenti principali che compongono l'API Google Classroom. L'API Google Classroom è composta da risorse e servizi. Le risorse rappresentano entità in Google Classroom, ad esempio un corso o un compito, e i servizi le recuperano e gestiscono. Alcune di queste entità hanno proprietà aggiuntive specifiche dell'API oltre a quelle esistenti in Classroom. I tipi di entità principali sono:

Entità	Rappresentazione in Classroom
Corsi	Un corso, ad esempio "M. Matematica del 4° periodo di Smith".
Soprannomi	Un ID alternativo per un corso.
Inviti	Un modo per aggiungere utenti a un corso.
Studenti	Uno studente di un corso.
Insegnanti	Un insegnante in un corso.
Profili utente	Un utente in senso più generico, al di fuori del contesto di studente o insegnante.
CourseWork	Un compito in un corso.
StudentSubmissions	Il lavoro di uno studente per un determinato compito, ad esempio risposte o fogli di lavoro.
CourseWorkMaterials	Materiali per gli studenti di un corso.
Annunci	Un annuncio per gli studenti di un corso.
AddOnAttachment	Contenuti o un'attività in un compito o materiale che in genere vengono visualizzati come iframe incorporati.
Argomenti	Un raggruppamento visivo di compiti e materiali in un corso.
Registrazioni	Un'istruzione per inviare notifiche alla tua app per le modifiche ai dati, ad esempio l'elenco degli studenti di un corso.

La maggior parte delle risorse dispone di metodi di servizio per le operazioni standard come lettura, aggiornamento ed eliminazione delle istanze della risorsa. Alcune risorse hanno anche metodi personalizzati per altre operazioni, come la modifica dell'elenco di studenti a cui è stato assegnato un determinato compito.

Per informazioni dettagliate sulle risorse e sui metodi dell'API, consulta la documentazione di riferimento per l'API Classroom.

Panoramica delle relazioni delle risorse

• Corso è l'oggetto di dati di base in Google Classroom.
• Gli alias vengono utilizzati come identificatori alternativi per Courses.
• Gli inviti vengono utilizzati per invitare profili utente a diventare insegnanti o studenti in un Course, ma gli utenti possono anche essere aggiunti direttamente dagli amministratori di dominio Google Workspace for Education.
• Gli insegnanti creano elementi di stream e li condividono con gli studenti dei loro corsi. I possibili tipi di elementi dello stream sono Coursework, CourseWorkMaterials e Announcements. CourseWork e CourseWorkMaterials possono essere organizzati visivamente in Argomenti e possono contenere AddOnAttachments. Gli studenti inviano StudentSubmissions per il loro CourseWork.
• Gli sviluppatori possono creare registrazioni per ricevere notifiche quando alcuni di questi dati cambiano.

Google Classroom è disponibile per i domini che si abbonano a Google Workspace for Education. In genere, un dominio nel contesto di Classroom rappresenta un distretto scolastico. Puoi creare un dominio di test Google Workspace for Education a scopo di sviluppo, che ti consente di controllare un'istanza di produzione di Classroom senza influire sugli utenti reali.

Corsi e alias

Courses rappresenta una classe, ad esempio "M. Matematica del 4° periodo di Smith", nonché gli insegnanti assegnati, l'elenco degli studenti e i metadati. Ogni corso è identificato da un ID univoco assegnato dal server. La risorsa Course incapsula in modo specifico tutti i metadati del corso, come nome, descrizione, località e ora. Gli elenchi degli studenti dei corsi vengono gestiti tramite le risorse Studente, Insegnante e Invito e i relativi metodi.

Aliases sono identificatori alternativi per un corso che possono essere associati a un corso e utilizzati al posto dell'ID univoco. Ogni alias esiste in uno spazio dei nomi che limita chi può crearlo e visualizzarlo. Sono supportati due spazi dei nomi:

• Dominio:lo spazio dei nomi di dominio è utile per creare alias a cui tutti gli utenti devono accedere, ma che non sono specifici di un determinato programma. Ad esempio, nello spazio dei nomi del dominio devono essere create schede alternative per un corso, ad esempio MATE 127 e INGINF 127. Gli alias nello spazio dei nomi del dominio possono essere creati solo dagli amministratori del dominio, ma sono visibili a tutti gli utenti di un dominio.
• Progetto sviluppatore: lo spazio dei nomi del progetto sviluppatore è utile per gestire gli alias specifici di un'applicazione. Ad esempio, un'applicazione che utilizza identificatori alternativi per i corsi può creare alias per mappare il proprio identificatore ai corsi di Classroom. Gli alias creati in questo spazio dei nomi sono collegati a una console API di Google specifica. Qualsiasi utente di un'applicazione può creare e visualizzare gli alias nello spazio dei nomi per il progetto sviluppatore dell'applicazione.

Per ulteriori informazioni sulla gestione dei metadati e degli alias dei corsi, consulta Gestire i corsi.

Elenchi degli studenti e utenti dei corsi

Students e Teachers sono mappature specifiche tra un profilo utente e un corso, che rappresentano il ruolo dell'utente nel corso. Le designazioni di studente e insegnante non sono globali: un utente può essere assegnato come insegnante per un corso e come studente per un altro. La designazione "studente" o "insegnante" rappresenta un insieme di autorizzazioni per un determinato utente in un determinato corso.

Studenti

Una risorsa Student rappresenta un utente iscritto come studente a un corso specifico.

Gli studenti possono visualizzare i dettagli del corso e gli insegnanti del corso.

Insegnanti

Una risorsa Teacher rappresenta un utente che insegna un corso specifico.

Gli insegnanti possono visualizzare e modificare i dettagli dei corsi, visualizzare insegnanti e studenti e gestire altri insegnanti e studenti.

Invitations e i metodi associati offrono un modo pratico per aggiungere studenti e insegnanti ai corsi. La creazione di inviti consente agli utenti di scegliere se partecipare o meno a un corso, anziché aggiungerli direttamente tramite le risorse per insegnanti e studenti.

UserProfiles rappresenta una mappatura al profilo di dominio di un utente come identificato dall'ID univoco o dall'indirizzo email dell'utente restituito dall'API Directory. L'utente corrente può anche fare riferimento al proprio ID utilizzando la scorciatoia "me".

Il servizio UserProfiles può essere utilizzato anche per gestire e invitare i Guardians, che rappresentano una mappatura tra uno studente e un tutore. I tutori in Classroom hanno accesso ad alcune informazioni degli studenti, come i loro compiti.

Per saperne di più sulla gestione degli elenchi, consulta Gestire insegnanti e studenti.

Attività del corso e contenuti inviati dagli studenti

Un elemento CourseWork rappresenta una singola attività assegnata a un gruppo di studenti di un corso. Contiene dettagli come descrizione, data di consegna e materiali, nonché metadati come l'ora di creazione. I materiali includono un titolo, una miniatura e un URL, nonché un identificatore che può essere utilizzato con le API appropriate (ad es. Drive, YouTube).

Gli elementi CourseWork descrivono uno dei seguenti tipi di attività:

• Un compito che gli studenti completano inviando fogli di lavoro o altri allegati.
• Una domanda a risposta breve o a scelta multipla.

Il lavoro dello studente per un elemento CourseWork è rappresentato da un StudentSubmission. È costituito da una risposta e da metadati aggiuntivi, come uno stato e il voto assegnato.

I contenuti di un StudentSubmission dipendono dal tipo di elemento corrispondenteCourseWork:

• I fogli di lavoro e gli allegati inviati per un compito, inclusi titolo, miniatura e URL, nonché identificatori che possono essere utilizzati con le API appropriate come Drive o YouTube.
• La risposta a una domanda a risposta breve o a scelta multipla.

Per ulteriori informazioni sulla gestione dei lavori del corso e dei contenuti inviati dagli studenti, consulta Gestire i lavori del corso.

Materiali e annunci del corso

In modo simile a CourseWork, i CourseWorkMaterials rappresentano i contenuti assegnati a un gruppo di studenti di un corso, con dettagli come il titolo e la descrizione e i materiali. Tuttavia, a differenza di CourseWork, CourseWorkMaterials non richiede agli studenti di inviare elementi. Pertanto, non è prevista una data di scadenza e StudentSubmissions non esiste per CourseWorkMaterials. Gli insegnanti possono utilizzare CourseWorkMaterials, ad esempio, per pubblicare suggerimenti di letture, un programma didattico o regole per la classe.

Announcements rappresentano anche i contenuti condivisi con un gruppo di studenti, ma non hanno dettagli come un titolo e non possono essere organizzati per Topics come CourseWork o CourseWorkMaterials. Gli insegnanti potrebbero utilizzarli per comunicare promemoria o avvisi al corso.

Argomenti

Topics vengono utilizzati per organizzare visivamente CourseWork e CourseWorkMaterials all'interno di un corso. Ad esempio, potresti utilizzarli per raggruppare i compiti in "facoltativo" e "obbligatorio" oppure in "modulo 1" e "modulo 2".

Componenti aggiuntivi di Classroom

Un componente aggiuntivo è un'interfaccia utente e un backend forniti dagli sviluppatori, in genere visualizzati in un frame. I componenti aggiuntivi vengono visualizzati come allegati in un elemento dello stream. L'elemento stream può essere Announcements, CourseWork o CourseWorkMaterials. Gli allegati dei componenti aggiuntivi sono rappresentati da un AddOnAttachment.

Gli allegati dei componenti aggiuntivi possono essere un'attività o un contenuti.

• Gli allegati delle attività richiedono che lo studente completi e consegni un singolo compito. Alcuni esempi sono quiz, disegni o giochi. Se vuoi, puoi valutare i contenuti inviati per un'attività.
• Gli allegati dei contenuti non richiedono l'invio da parte degli studenti. Lo studente non deve consegnare l'allegato e quest'ultimo non viene valutato. Alcuni esempi sono foto, articoli e video.

Per scoprire di più, consulta le guide per lo sviluppo di componenti aggiuntivi.

Registrazioni

Le applicazioni possono iscriversi per ricevere notifiche quando determinati dati cambiano in Google Classroom. Ad esempio, quando viene aggiornato l'elenco degli studenti di un corso. Registrations rappresenta un'istruzione per inviare queste notifiche alla tua applicazione.

Per saperne di più, consulta la guida alle notifiche push.