傳回檔案的特定欄位

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

根據預設，伺服器會傳回所查詢資源專屬的一組欄位。舉例來說，files.get 方法可能只會傳回 files 資源的 id、name 和 mimeType。permissions.get 方法會針對 permissions 資源傳回不同的預設欄位組合。

伺服器處理包含 fields 查詢參數的有效要求之後，會傳回 HTTP 200 OK 狀態碼以及要求的資料。如果欄位查詢參數發生錯誤或無效，伺服器會傳回 HTTP 400 Bad Request 狀態碼，以及指出選取欄位錯誤的錯誤訊息。舉例來說，files.list(fields='files(id,capabilities,canAddChildren)') 會產生「Invalid field selected 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=role 或 fields=*)。
  • files.get (使用 fields=permissions(role) 或 fields=permissions/role)。
  • files.get 搭配 fields=permissions 以暗示巢狀資源的所有欄位。
  • changes.list (使用fields=changes(file(permissions(role))))。

如要擷取多個欄位，請使用以逗號分隔的清單。例如，files.list 和 fields=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"
    }
  ]
}