傳回特定欄位

如要傳回所需確切欄位並提升效能，請在方法呼叫中使用 fields 系統參數。

本文說明如何在 Google 雲端硬碟中使用 fields 參數。

欄位參數的運作方式

fields 參數會使用 FieldMask 篩選回應。欄位遮罩用於指定要求應傳回的欄位子集。使用欄位遮罩是良好的設計做法，可確保您不會要求不必要的資料，進而避免不必要的處理時間。

如未指定 fields 參數，伺服器會傳回方法專屬的預設欄位集。舉例來說，files 方法的 list 方法只會傳回 kind、id、name 和 mimeType 欄位。permissions 資源的 get 方法會傳回一組不同的預設欄位。

對於 about、comments (不含 delete) 和 replies (不含 delete) 資源的所有方法，您必須設定 fields 參數。這些方法不會傳回一組預設欄位。

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

如要判斷可使用 fields 參數傳回的欄位，請前往您要查詢的資源說明文件頁面。舉例來說，如要查看可為檔案傳回的欄位，請參閱 files 資源說明文件。如要瞭解更多檔案專屬的查詢字詞，請參閱「搜尋查詢字詞和運算子」。

欄位參數格式規則

fields 要求參數值的格式約略以 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。
  • permissions.get fields=* 即可顯示所有 permissions 欄位。
  • files.get，搭配 fields=permissions(role) 或 fields=permissions/role 使用。
  • files.get fields=permissions 即可顯示所有 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"
    }
  ]
}