Restituisci 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, consulta Parametri di sistema alternativi.

Come funziona il parametro fields

Il parametro fields utilizza un FieldMask per il filtro 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 assicurarti 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 list metodo sulla risorsa files restituisce solo i campi kind, id, name e mimeType. Il metodo get sulla risorsa permissions restituisce un insieme diverso di campi predefiniti.

Per tutti i metodi delle risorse about, approvals, 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 un errore di "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 della documentazione della risorsa su cui stai eseguendo la query. Ad esempio, per vedere quali campi puoi restituire per un file, consulta la documentazione della risorsa files. Per ulteriori termini di query specifici per i file, consulta Termini e operatori delle query di ricerca.

Regole di formato dei parametri dei campi

Il formato del valore parametro 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 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 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ò influire negativamente sulle prestazioni della richiesta.

  • Non puoi selezionare singoli elementi di una mappa quando le chiavi contengono caratteri speciali (ad esempio barre / o punti .). Ad esempio, se tenti di selezionare una chiave di formato di esportazione specifica in exportLinks utilizzando fields=exportLinks/application/pdf, viene generato un errore HTTP 400 Bad Request perché il parser del percorso interpreta / come delimitatore di proprietà nidificata. Per recuperare coppie chiave-valore con caratteri speciali nelle chiavi, richiedi l'intera mappa (ad esempio fields=exportLinks) e filtra i risultati lato client.

Richiesta

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

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

Per specificare i campi nidificati all'interno di array o oggetti nidificati, utilizza le parentesi nidificate. Ad esempio, per elencare i file con ID, nome e dettagli del proprietario nidificati (nome visualizzato e indirizzo email) recuperando anche il token della pagina successiva per l'impaginazione: files.list con fields=nextPageToken,files(id,name,owners(displayName,emailAddress)).

Richiesta

In questo esempio, forniamo il parametro del percorso dell'ID file e più campi, inclusi alcuni campi della risorsa delle autorizzazioni nidificata, 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.