傳回特定欄位

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

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

根據預設，伺服器會傳回特定於所查詢資源的欄位組合。舉例來說，files 資源上的 get() 方法可能只會傳回 id、name 和 mimeType。permissions 資源上的 get() 方法會傳回不同的預設欄位組合。

伺服器處理包含 fields 參數的有效要求後，會傳回 HTTP 200 OK 狀態碼，以及所要求的資料。如果 fields 參數發生錯誤或無效，伺服器會傳回 HTTP 400 Bad Request 狀態碼和錯誤訊息，指出您選擇的欄位有何問題。舉例來說，files.list(fields='files(id,capabilities,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 欄位。
  • fields=changes(file(permissions(role)))會員價 changes.list()。

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