Come funzionano le richieste

Questa pagina fornisce una panoramica generale del funzionamento delle richieste nell'API Google Classroom. L'obiettivo è aiutare i lettori che non hanno familiarità con la progettazione orientata alle risorse o con le API Google Workspace.

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

Progettazione orientata alle risorse

Come indicato in Risorse API, l'API Classroom segue 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 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() sulla risorsa Course e specifica name e description nella richiesta, insieme a informazioni facoltative come room.

Per le risorse secondarie (a volte chiamate risorse figlio), sono necessari 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 CourseWork.

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

Patch

Per modificare le risorse esistenti, chiama il metodo patch() (talvolta chiamato update()) sulla risorsa corrispondente. Il metodo patch() è quasi identico a create(), con due differenze fondamentali: 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 a metodi patch(). Sebbene entrambi modificano una risorsa, si differenziano nel comportamento. Update() sostituisce completamente una risorsa con una nuova, mentre patch() aggiorna solo i campi selezionati. Ad esempio, courses.update() sostituisce un intero Course esistente, mentre courses.patch() utilizza il fieldMask sopra menzionato per modificare solo campi specifici nel Course. Per semplicità, l'API Google Classroom utilizza quasi esclusivamente patch() ed è consigliabile utilizzare questo metodo in generale.

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

Ottieni ed elenca

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

Il metodo get() recupera una risorsa specifica in base a un identificatore. Ad esempio, recuperare 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 di risorsa individuali. Spesso l'operazione list() recupera tutte le risorse secondarie di una risorsa principale, ad esempio tutti i CourseWork all'interno di un Course. Ciò è utile per ridurre al minimo le richieste rispetto all'esecuzione di più chiamate get() ed è particolarmente utile quando non conosci l'id delle risorse che ti interessano.

In genere, i metodi list() hanno una quantità massima di risorse che possono essere restituite in una singola chiamata e i limiti inferiori possono essere configurati includendo un valore pageSize nella chiamata. Nei casi in cui le risorse sono più del limite, il metodo list() supporta la paginazione; ogni "pagina" di risultati restituita fornisce un pageToken, che può essere incluso in una successiva chiamata list() per recuperare il batch successivo di risorse.

Elimina

Il metodo delete() accetta un identificatore di 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 per ciascuno di essi.