Restituire campi specifici

Per restituire i campi esatti di cui hai bisogno e migliorare le prestazioni, utilizza il fieldsparametro di sistema nella chiamata al metodo.

Questo documento spiega come utilizzare il parametro fields in Google Drive.

Come funziona il parametro fields

Il parametro fields utilizza un FieldMask per il filtraggio delle risposte. Le maschere di campo vengono utilizzate per specificare un sottoinsieme di campi che una richiesta deve restituire. L'utilizzo di una maschera di campo è una buona pratica di progettazione per assicurarsi di non richiedere dati non necessari, il che a sua volta aiuta a evitare tempi di elaborazione non necessari.

Se non specifichi il parametro fields, il server restituisce un insieme predefinito di campi specifici per il metodo. Ad esempio, il metodo list sul metodo files restituisce solo i campi kind, id, name e mimeType. Il metodo get nella risorsa permissions restituisce un insieme diverso di campi predefiniti.

Per tutti i metodi delle risorse about, comments (escluso delete) e replies (escluso delete), devi impostare il parametro fields. Questi metodi non restituiscono un insieme predefinito di campi.

Dopo che un server elabora una richiesta valida che include il parametro fields, restituisce un codice di stato HTTP 200 OK, insieme ai dati richiesti. Se il parametro fields presenta un errore o non è valido, il server restituisce un codice di stato HTTP 400 Bad Request, insieme a un messaggio di errore che indica cosa non va nella selezione dei campi. Ad esempio, files.list(fields='files(id,capabilities,canAddChildren)') genera l'errore "Invalid field selection canAddChildren." Il parametro fields corretto per questo esempio è files.list(fields='files(id,capabilities/canAddChildren)').

Per determinare i campi che puoi restituire utilizzando il parametro fields, visita la pagina di documentazione della risorsa che stai interrogando. Ad esempio, per vedere quali campi puoi restituire per un file, consulta la documentazione della risorsa files. Per altri termini di query specifici per i file, vedi Termini e operatori di query di ricerca.

Regole di formattazione dei parametri di campo

Il formato del valore del parametro di richiesta dei campi si basa vagamente sulla sintassi XPath. Di seguito sono riportate le regole di formattazione per il parametro fields. Tutte queste regole utilizzano esempi relativi al metodo files.get.

  • Utilizza un elenco separato da virgole per selezionare più campi, ad esempio 'name, mimeType'.

  • Utilizza a/b per selezionare il campo b nidificato all'interno del campo a, ad esempio 'capabilities/canDownload'. Per ulteriori informazioni, vedi Recuperare i campi di una risorsa nidificata.

  • Utilizza un selettore secondario per richiedere un insieme di campi secondari specifici di array o oggetti inserendo le espressioni tra parentesi "()". Ad esempio, 'permissions(id)' restituisce solo l'ID autorizzazione per ogni elemento dell'array permissions.

  • Per restituire tutti i campi di un oggetto, utilizza un asterisco (*) come carattere jolly nelle selezioni dei campi. Ad esempio, 'permissions/permissionDetails/*' seleziona tutti i campi dei dettagli delle autorizzazioni disponibili per autorizzazione. Tieni presente che l'utilizzo del carattere jolly può influire negativamente sul rendimento della richiesta.

Richiedi

In questo esempio, forniamo il parametro di percorso dell'ID file e più campi come parametro di query nella richiesta. La risposta restituisce i valori dei campi per l'ID file.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

Risposta

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

Recuperare i campi di una risorsa nidificata

Quando un campo fa riferimento a un'altra risorsa, puoi specificare quali campi della risorsa nidificata devono essere recuperati.

Ad esempio, per recuperare il campo role (risorsa nidificata) della risorsa permissions, utilizza una delle seguenti opzioni:

  • permissions.get con fields=role.
  • permissions.get con fields=* per mostrare tutti i campi permissions.
  • files.get con fields=permissions(role) o fields=permissions/role.
  • files.get con fields=permissions per mostrare tutti i campi permissions.
  • changes.list con fields=changes(file(permissions(role))).

Per recuperare più campi, utilizza un elenco separato da virgole. Ad esempio, files.list con fields=files(id,name,createdTime,modifiedTime,size).

Richiedi

In questo esempio, forniamo il parametro di percorso dell'ID file e più campi, inclusi alcuni campi della risorsa delle autorizzazioni nidificate, come parametro di query nella richiesta. La risposta restituisce i valori dei campi per l'ID file.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)

Risposta

{
  "name": "File1",
  "starred": false,
  "shared": true,
  "permissions": [
    {
      "kind": "drive#permission",
      "type": "user",
      "role": "owner"
    }
  ]
}