Restituire campi specifici

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

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.

Per impostazione predefinita, il server restituisce un insieme di campi specifici della risorsa su cui viene eseguita la query. Ad esempio, il metodo get() della risorsa files potrebbe restituire solo id, name e mimeType. Il metodo get() nella risorsa permissions restituisce un insieme diverso di campi predefiniti.

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.

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