返回文件的特定字段

如需返回您所需的确切字段并提高性能,请使用 fields 查询参数。

默认情况下,服务器会发回一组特定于要访问的资源的字段, 已查询。例如,files.get 方法可能只返回 idnamemimeType files 资源。通过 permissions.get 方法会返回 一组不同的默认字段 permissions 资源。

服务器处理完包含 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)' 仅返回 权限数组。

  • 要返回某个对象中的所有字段,请在字段中使用星号作为通配符 选择。例如,'permissions/permissionDetails/*' 会选择 每个权限可用的权限详细信息字段。请注意,使用 此通配符会对请求的性能产生负面影响。

显示示例

请求

在此示例中,我们在请求中提供了文件 ID 路径参数和多个字段作为查询参数。该响应会返回文件 ID 的字段值。

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

答案

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

提取嵌套资源的字段

当一个字段引用另一个资源时,您可以指定 嵌套资源。

例如,如需检索 permissionsrole 字段(嵌套资源), 请使用以下任一选项:

  • permissions.get 替换为 fields=rolefields=*
  • files.get 替换为 fields=permissions(role)fields=permissions/role
  • files.getfields=permissions 搭配使用,这表示嵌套元素的所有字段 资源。
  • 使用 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"
    }
  ]
}