Come funzionano le richieste

Questa pagina descrive una panoramica generale del funzionamento delle richieste nell'API Google Classroom. L'obiettivo è aiutare i lettori che non hanno ancora familiarità con il design orientato alle risorse o con le API di Google Workspace.

Per esempi di codice specifici, consulta le guide all'API corrispondenti, ad esempio Creare e gestire i corsi o Creare e gestire i corsi.

Progettazione orientata alle risorse

Come indicato nella sezione Struttura dell'API, l'API Classroom segue i pattern di progettazione orientata alle risorse. La maggior parte delle risorse dispone di metodi per operazioni standard come la creazione, la lettura, l'aggiornamento e l'eliminazione di istanze della risorsa.

Ad esempio, è possibile create(), patch(), get(), list() e delete() un corso Course di Classroom utilizzando l'API.

Crea

Per creare una nuova risorsa, ad esempio un Course, chiama il metodo create() per la risorsa corrispondente.

Le chiamate Create() richiedono sempre come input i dettagli iniziali e critici della risorsa corrispondente. Ad esempio, per creare un Course, chiama il metodo create() nella risorsa Course e specifica name e description nella richiesta, insieme a informazioni facoltative come room.

Per le risorse secondarie (a volte chiamate risorse secondarie), sono obbligatori anche gli identificatori della risorsa principale. Ad esempio, quando crei un CourseWork all'interno di un Course, è necessario il Course id per stabilire a quale Course appartiene il CourseWork.

I metodi Create() restituiscono un'istanza della risorsa appena creata nella risposta alla chiamata dell'API. La risorsa restituita in genere contiene eventuali campi aggiuntivi generati dal server, come la risorsa id o creationTime.

Patch

Per modificare le risorse esistenti, chiama il metodo patch() (a volte chiamato update()) sulla risorsa corrispondente. Il metodo patch() è quasi identico a create(), con due differenze principali: quando chiami il metodo patch(), devi specificare:

1. Il id della risorsa da modificare.
2. Un elenco di campi, chiamato updateMask, per determinare quali campi della risorsa aggiornare. Questo è facoltativo nei casi in cui è presente un insieme predefinito di campi o i campi vengono dedotti.

Suggerimento: potresti notare metodi update() insieme ai metodi patch(). Sebbene entrambi modifichino una risorsa, il loro comportamento è diverso. Update() sostituisce completamente una risorsa con una nuova, mentre patch() aggiorna solo alcuni campi. Ad esempio, courses.update() sostituisce un intero Course esistente, mentre courses.patch() utilizza il suddetto fieldMask per modificare solo campi specifici nel Course. Per semplicità, l'API Google Classroom utilizza quasi esclusivamente patch() e ti consigliamo di utilizzare questo metodo in generale.

I metodi Patch() restituiscono l'istanza completa della risorsa aggiornata nella risposta alla chiamata dell'API, con tutte le modifiche completate.

Get e list

Esistono due metodi per recuperare le risorse: get() e list().

Il metodo get() recupera una risorsa specifica in base a un identificatore. Ad esempio, il recupero di un Course in base a id o alias. La chiamata get() restituisce direttamente la risorsa completa.

Il metodo list() recupera più risorse dello stesso tipo in un'unica richiesta, senza la necessità degli identificatori delle singole risorse. Spesso l'operazione list() recupera tutte le risorse secondarie di una risorsa principale, ad esempio recuperando tutti i CourseWork all'interno di un Course. Questa operazione è utile per minimizzare le richieste rispetto all'esecuzione di più chiamate get() ed è particolarmente preziosa quando non conosci il id delle risorse che ti interessano.

In genere, i metodi list() hanno un numero massimo di risorse che possono essere rese in una singola chiamata e i limiti inferiori possono essere configurati includendo un valore pageSize con la chiamata. Se le risorse sono più del limite, il metodo list() supporta l'impaginazione: ogni "pagina" di risultati restituita fornisce un pageToken, che può essere incluso in una chiamata list() successiva per recuperare il batch successivo di risorse.

Elimina

Il metodo delete() accetta un identificatore della risorsa, ad esempio id, ed elimina la risorsa corrispondente. Se l'operazione delete() ha esito positivo, viene restituita una risposta vuota.

Altre operazioni

Non tutte le operazioni possibili con l'API Classroom possono essere eseguite con le operazioni standard sopra menzionate, ad esempio la modifica degli assegnatari di una risorsa CourseWork. In questi casi, sono disponibili metodi personalizzati, come il metodo modifyAssignees. Il comportamento di questi metodi è personalizzato e devi consultare la documentazione relativa a ciascuno di essi.