傳回檔案的特定欄位

如要傳回確切需要的欄位並改善效能，請在方法呼叫中使用 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 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 欄位 (巢狀資源)，請使用下列任一選項：

  • 搭配 fields=role 或 fields=* 使用 permissions.get。
  • 搭配 fields=permissions(role) 或 fields=permissions/role 使用 files.get。
  • 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"
    }
  ]
}