返回文件的特定字段

如需返回您需要的确切字段并提高性能,请在方法调用中使用 fields 查询参数。

默认情况下,服务器会发回特定于所查询资源的一组字段。例如,files.get 方法可能仅返回 files 资源的 idnamemimeTypepermissions.get 方法会为 permissions 资源返回一组不同的默认字段。

服务器处理完包含 fields 查询参数的有效请求之后,会发回 HTTP 200 OK 状态代码以及所请求的数据。如果 fields 查询参数存在错误或因其他原因而无效,服务器会返回 HTTP 400 Bad Request 状态代码以及一条错误消息,说明您选择的字段存在什么问题。例如,files.list(fields='files(id,capabilities,canAddChildren)') 会产生错误“Invalid field selection 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.getfields=rolefields=* 结合使用。
  • files.getfields=permissions(role)fields=permissions/role 结合使用。
  • files.getfields=permissions 结合使用,即可暗示嵌套资源的所有字段。
  • 使用 fields=changes(file(permissions(role))) 调用 changes.list

如需检索多个字段,请使用以英文逗号分隔的列表。例如,将 files.listfields=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"
    }
  ]
}