Risorse API

Questa guida fornisce una panoramica dei componenti principali che costituiscono l'API Google Classroom. L'API Google Classroom è costituita da risorse e servizi. Le risorse rappresentano entità in Google Classroom, come un corso o un compito, e i servizi recuperano e gestiscono queste risorse. 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	Una classe, ad esempio "M. Smith's 4th period math" (matematica del quarto periodo di Smith).
Alias	Un ID alternativo per un corso.
Inviti	Un modo per aggiungere utenti a un corso.
Studenti	Uno studente di un corso.
Insegnanti	Un insegnante di un corso.
Profili utente	Un utente in modo 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 attività in un compito o materiale che vengono in genere visualizzati come iframe incorporato.
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 un elenco degli studenti del corso.

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

Per informazioni dettagliate sulle risorse e sui metodi dell'API, consulta il riferimento API Classroom.

Panoramica delle relazioni tra risorse

• Il 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 i 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 del flusso e li condividono con gli studenti dei loro corsi. I possibili tipi di elementi del flusso sono Coursework, CourseWorkMaterials e Announcements. CourseWork e CourseWorkMaterials possono essere organizzati visivamente in Argomenti e possono contenere Allegati di componenti aggiuntivi. 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. Un dominio nel contesto di Classroom in genere rappresenta un distretto scolastico. Puoi creare un dominio di test di 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 rappresentano una classe, ad esempio "M. Matematica del 4° periodo di Smith" e i relativi insegnanti assegnati, elenco degli studenti e metadati. Ogni corso è identificato da un ID univoco assegnato dal server. La risorsa Course in particolare contiene tutti i metadati del corso, come nome, descrizione, posizione e ora. Gli elenchi 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 programma. Ad esempio, gli elenchi alternativi per un corso, come MATH 127 e COMSCI 127, devono essere creati nello spazio dei nomi del dominio. Gli alias nello spazio dei nomi del dominio possono essere creati solo dagli amministratori di 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 associati a una console API di Google specifica. Qualsiasi utente di un'applicazione può creare e visualizzare alias nello spazio dei nomi del progetto sviluppatore dell'applicazione.

Per saperne di più sulla gestione dei metadati e degli alias dei corsi, vedi Gestire i corsi.

Elenchi dei corsi e utenti

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 in un altro. La dicitura "studente" o "insegnante" rappresenta un insieme di autorizzazioni per un determinato utente in un determinato corso. Un corso può avere più di un insegnante o zero studenti. Insegnanti e studenti possono essere aggiunti o rimossi da un corso in qualsiasi momento.

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 sono autorizzati a visualizzare e modificare i dettagli del corso, visualizzare insegnanti e studenti e gestire insegnanti e studenti aggiuntivi.

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

UserProfiles rappresentano una mappatura al profilo di dominio di un utente identificato dall'ID univoco o dall'indirizzo email dell'utente restituito dall'API Directory. L'utente attuale può anche fare riferimento al proprio ID utilizzando l'abbreviazione "me".

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

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

Elementi dello stream

Gli elementi del flusso sono i contenuti pubblicati condivisi con i membri di un corso. Sviluppatori e insegnanti possono creare tre tipi di elementi del flusso: Announcement, CourseWork e CourseWorkMaterial.

Gli insegnanti creano Announcements nella parte superiore della pagina Stream nell'interfaccia utente di Classroom. Gli insegnanti creano CourseWork e CourseWorkMaterials facendo clic sul pulsante Crea nella scheda Lavori del corso. Gli sviluppatori possono creare tutti i tipi di elementi del flusso a livello di programmazione tramite l'API Classroom.

Di seguito sono riportate le caratteristiche degli elementi del flusso:

• Tutti gli elementi del flusso possono contenere materiali supplementari, ad esempio file di Google Drive, video di YouTube, Moduli Google, collegamenti ipertestuali URL e allegati dei componenti aggiuntivi di Classroom.
• Tutti gli elementi dello stream possono essere assegnati a un sottoinsieme degli studenti del corso.
• Un CourseWork può essere valutato o meno. Gli insegnanti possono modificare lo stato di valutazione di un compito CourseWork in qualsiasi momento.
• Un elemento del flusso può avere più di un allegato.
• Un elemento del flusso può avere allegati di diversi tipi. Ad esempio, un CourseWork compito potrebbe avere contemporaneamente allegati di file di Google Drive, video di YouTube e componenti aggiuntivi di Classroom.
• Un elemento del flusso potrebbe avere allegati aggiuntivi di più sviluppatori.
• Gli sviluppatori possono ottenere e modificare i dettagli di qualsiasi risorsa di elemento Stream che abbia uno dei loro allegati del componente aggiuntivo.
• Gli sviluppatori possono consegnare, recuperare o restituire i contenuti inviati da uno studente per un compito CourseWork che include uno dei loro allegati del componente aggiuntivo.
• Gli sviluppatori possono finalizzare i voti solo per i singoli invii degli studenti nei compiti che hanno creato.

Elementi dello stream copiati

Gli insegnanti possono copiare un elemento dello stream copiando un corso, riutilizzando un compito o pubblicando un elemento dello stream in più corsi. Tutte le nuove copie avranno identificatori distinti, il che potrebbe essere un aspetto importante se stai sviluppando un componente aggiuntivo di Classroom. Leggi la nostra guida sui contenuti copiati per capire come un componente aggiuntivo può gestire questi scenari.

CourseWork e StudentSubmissions

Un elemento CourseWork rappresenta un compito per un gruppo di studenti di un corso. È l'unico tipo di elemento dello stream che può accettare un invio da parte di uno studente. Una risorsa CourseWork contiene dettagli come la descrizione, la data di scadenza, il voto massimo e metadati come l'ora di creazione.

Ogni risorsa CourseWork descrive 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 un grado assegnato.

I contenuti di un StudentSubmission dipendono dal tipo di elemento CourseWork corrispondente e possono includere:

• I fogli di lavoro e gli allegati inviati per un compito, inclusi titolo, miniatura e URL, nonché gli 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 saperne di più sulla gestione dei corsi e dei compiti consegnati dagli studenti, consulta Gestire i corsi.

CourseWorkMaterials e Announcements

Analogamente a CourseWork, CourseWorkMaterials rappresentano i contenuti assegnati a un gruppo di studenti di un corso. Ogni risorsa ha dettagli come titolo e descrizione, oltre a materiali supplementari. Tuttavia, a differenza di CourseWork, CourseWorkMaterials non richiedono agli studenti di inviare artefatti. Pertanto, non esiste una data di scadenza e StudentSubmissions non esiste per CourseWorkMaterials. Gli insegnanti possono utilizzare CourseWorkMaterials per pubblicare letture consigliate, un programma di studio o le regole del corso.

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 possono utilizzarli per comunicare promemoria o avvisi al corso.

Argomenti

Topics vengono utilizzati per organizzare visivamente CourseWork e CourseWorkMaterials all'interno di un corso. Questi tag possono essere utilizzati per raggruppare i compiti in "facoltativi" e "obbligatori" o "unità 1" e "unità 2", ad esempio.

Componenti aggiuntivi di Classroom

Un componente aggiuntivo è un'interfaccia utente e un backend forniti dallo sviluppatore e in genere visualizzati in un iframe. I componenti aggiuntivi vengono visualizzati come allegati in un elemento dello stream. L'elemento dello stream può essere qualsiasi 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 contenuto.

• Gli allegati delle attività richiedono che uno studente completi e consegni un invio individuale. Alcuni esempi sono quiz, disegni o giochi. Facoltativamente, un invio di attività può essere valutato.
• Gli allegati dei contenuti non richiedono l'invio di un compito da parte dello studente. Lo studente non deve consegnare l'allegato e non viene valutato. Alcuni esempi sono foto, articoli e video.

Per saperne 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 di un corso. Registrations rappresentano un'istruzione per inviare queste notifiche alla tua applicazione.

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