Restituire campi specifici

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

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

Per informazioni su altri parametri di sistema che si applicano all'API Drive, vedi Parametri di sistema alternativi.

Come funziona il parametro fields

Il parametro fields utilizza una FieldMask per il filtraggio delle risposte. Le maschere dei campi 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 ha elaborato 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 il problema relativo alla selezione dei campi. Ad esempio, files.list(fields='files(id,capabilities,canAddChildren)') genera l'errore "Invalid field selection canAddChildren." Il parametro 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 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, consulta Termini e operatori delle query di ricerca.

Regole di formattazione dei parametri dei campi

Il formato del valore del parametro di richiesta fields si basa liberamente 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 saperne di più, consulta Recuperare i campi di una risorsa nidificata.

  • Utilizza un selettore secondario per richiedere un insieme di sottocampi specifici di array o oggetti inserendo le espressioni tra parentesi "()". Ad esempio, 'permissions(id)' restituisce solo l'ID autorizzazione per ogni elemento nell'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.

Richiesta

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).

Richiesta

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"
    }
  ]
}

Parametri di sistema alternativi

I parametri di query che si applicano a tutte le operazioni dell'API Google Drive sono documentati in Parametri di sistema.