傳回檔案的特定欄位

如要傳回所需的確切欄位並改善成效，請使用 fields 參數。

根據預設，伺服器會傳回一組資源，其專用於該資源 。例如：files.get 方法可能只會傳回以下項目的 id、name 和 mimeType： files 資源。 permissions.get 方法會傳回 不同的預設欄位組合 permissions 資源。

伺服器處理包含 fields 查詢的有效要求之後 參數，它會傳回 HTTP 200 OK 狀態碼，以及所請求 資料。如果欄位查詢參數有誤或無效， 伺服器傳回 HTTP 400 Bad Request 狀態碼，以及發生錯誤 訊息，說明選取的欄位問題。例如： files.list(fields='files(id,capabilities,canAddChildren)') 會產生 「所選欄位無效 canAddChildren。」輸入的正確欄位查詢參數 也就是 files.list(fields='files(id,capabilities/canAddChildren)')。

如要判斷使用 fields 參數可以傳回哪些欄位，請造訪 查看該資源的說明文件頁面。舉例來說 可為檔案傳回的欄位，請參閱 files 資源說明文件。

欄位參數格式規則

欄位要求參數值的格式約略以 XPath 為基礎 語法。以下是 fields 參數的格式設定規則。所有的運算 這些規則會使用與 files.get 方法相關的範例。

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

  • 使用 a/b 在 a 欄位的巢狀結構中選取 b 欄位，例如 'capabilities/canDownload'。詳情請參閱擷取 巢狀 資源

  • 使用子選擇器來請求一組特定的陣列子欄位，或 物件。例如： 'permissions(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。
  • 帶有 fields=permissions 的 files.get 以表示巢狀結構的所有欄位 資源。
  • fields=changes(file(permissions(role)))會員價 changes.list。

如要擷取多個欄位，請使用逗號分隔的清單。例如： fields=files(id,name,createdTime,modifiedTime,size)會員價 files.list。

顯示範例

要求

在這個範例中，我們提供檔案 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"
    }
  ]
}