Restituire campi specifici

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

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

Come funziona il parametro fields

Il parametro fields utilizza un valore FieldMask per il filtro delle risposte. Le maschere di campo vengono utilizzate per specificare un sottoinsieme di campi che deve essere restituito da una richiesta. L'utilizzo di una maschera di campo è una buona prassi di progettazione per assicurarti di non richiedere dati non necessari, il che a sua volta contribuisce 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 del metodo files restituisce solo i campi kind, id, name e mimeType. Il metodo get della 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 HTTP 400 Bad Request contiene un errore o non è valido, il server restituisce un HTTP 400 Bad Request codice di stato, insieme a un messaggio di errore che indica il problema con la selezione dei campi. Ad esempio, files.list(fields='files(id,capabilities,canAddChildren)') genera un errore di "Selezione del campo non valida 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 della documentazione della risorsa su cui stai eseguendo la query. Ad esempio, per sapere 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 di query di ricerca.

Regole di formattazione dei parametri di campo

Il formato del valore del parametro di richiesta dei campi 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 nel campo a, ad esempio 'capabilities/canDownload'. Per ulteriori informazioni, consulta Recupero dei 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 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 per autorizzazione. Tieni presente che l'utilizzo del carattere jolly può comportare un impatto negativo sulle prestazioni della richiesta.

Mostra un esempio

Richiedi

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

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

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