傳回檔案的特定欄位

如要傳回您需要的精確欄位並改善效能,請在方法呼叫中使用 fields 查詢參數。

根據預設,伺服器會傳回一組查詢資源專屬的欄位。舉例來說,files.get 方法可能只會傳回 files 資源的 idnamemimeTypepermissions.get 方法會為 permissions 資源傳回一組不同的預設欄位。

伺服器處理包含 fields 查詢參數的有效要求後,會傳回 HTTP 200 OK 狀態碼,以及所要求的資料。如果欄位查詢參數有誤或無效,伺服器會傳回 HTTP 400 Bad Request 狀態碼和錯誤訊息,說明您選取的欄位有誤。例如,files.list(fields='files(id,capabilities,canAddChildren)') 會產生「Invalid field selection canAddChildren」的錯誤這個範例的正確欄位查詢參數為 files.list(fields='files(id,capabilities/canAddChildren)')

如要確定可使用 fields 參數傳回的欄位,請前往查詢資源的說明文件頁面。舉例來說,如要查看檔案可以傳回哪些欄位,請參閱 files 資源說明文件。

欄位參數格式規則

欄位要求參數值的格式大致上是以 XPath 語法為基礎。以下是 fields 參數的格式設定規則。所有規則都會使用與 files.get 方法相關的範例。

  • 請使用以逗號分隔的清單來選取多個欄位,例如 'name, mimeType'

  • 使用 a/b 選取在欄位 a 內的巢狀欄位 b,例如 'capabilities/canDownload'。詳情請參閱「擷取巢狀資源的欄位」。

  • 透過在括號「()」中放置運算式,使用子選取器要求一組特定的陣列或物件子欄位。舉例來說,'permissions(id)' 只會傳回權限陣列中每個元素的權限 ID。

  • 如要傳回物件中的所有欄位,請在欄位選取項目中使用星號做為萬用字元。舉例來說,'permissions/permissionDetails/*' 會選取每個權限所有可用的權限詳細資料欄位。請注意,使用這個萬用字元可能會導致要求對要求的效能造成負面影響。

顯示範例

要求

在這個範例中,我們在要求中提供檔案 ID 路徑參數和多個欄位做為查詢參數。回應會傳回檔案 ID 的欄位值。

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

回應

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

擷取巢狀資源的欄位

當欄位參照其他資源時,您可以指定應擷取巢狀資源的哪些欄位。

舉例來說,如要擷取 permissions 資源的 role 欄位 (巢狀資源),請使用下列任一選項:

  • permissions.get,搭配 fields=rolefields=* 使用。
  • files.get,搭配 fields=permissions(role)fields=permissions/role 使用。
  • files.getfields=permissions 表示巢狀資源的所有欄位。
  • changes.listfields=changes(file(permissions(role)))

如要擷取多個欄位,請使用以逗號分隔的清單。例如 files.listfields=files(id,name,createdTime,modifiedTime,size)

顯示範例

要求

在這個範例中,我們會在要求中提供檔案 ID 路徑參數和多個欄位 (包括巢狀權限資源的某些欄位) 做為查詢參數。回應會傳回檔案 ID 的欄位值。

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)

回應

{
  "name": "File1",
  "starred": false,
  "shared": true,
  "permissions": [
    {
      "kind": "drive#permission",
      "type": "user",
      "role": "owner"
    }
  ]
}