Restituire campi specifici per un file

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

Per impostazione predefinita, il server restituisce un insieme di campi specifici per la risorsa oggetto della query. Ad esempio, il metodo files.get potrebbe restituire solo id, name e mimeType per la risorsa files. Il metodo permissions.get restituisce un diverso insieme di campi predefiniti per una risorsa permissions.

Dopo che un server ha elaborato una richiesta valida che include il parametro di query fields, invia un codice di stato HTTP 200 OK insieme ai dati richiesti. Se il parametro di query dei campi presenta un errore o non è valido per altri motivi, il server restituisce un codice di stato HTTP 400 Bad Request e un messaggio di errore che indica cosa c'è che non va nella selezione dei campi. Ad esempio, files.list(fields='files(id,capabilities,canAddChildren)') restituisce l'errore "La selezione dei campi non valida canAddChildren". Il parametro di query dei campi 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 della documentazione della risorsa su cui stai eseguendo una query. Ad esempio, per vedere quali campi puoi restituire per un file, consulta la documentazione delle risorse files.

Regole di formattazione dei parametri di campo

Il formato del valore del parametro di richiesta dei campi è generico e si basa 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, consulta Recuperare i campi di una risorsa nidificata.

  • Utilizza un selettore secondario per richiedere un insieme di sottocampi specifici di array o oggetti inserendo espressioni tra parentesi "()". Ad esempio, 'permissions(id)' restituisce solo l'ID autorizzazione per ciascun elemento nell'array delle autorizzazioni.

  • 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 in base all'autorizzazione. Tieni presente che l'utilizzo di questo carattere jolly può portare a un impatto negativo sulle prestazioni della richiesta.

Mostra un esempio

Richiedi

In questo esempio, nella richiesta forniamo il parametro del percorso dell'ID file e più campi come parametro di ricerca. La risposta restituisce i valori del campo 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
  }
}

Recupera 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 o fields=*.
  • files.get con fields=permissions(role) o fields=permissions/role.
  • files.get con fields=permissions per implicare tutti i campi della risorsa nidificata.
  • 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).

Mostra un esempio

Richiedi

In questo esempio, forniamo il parametro del 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 del campo 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"
    }
  ]
}