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