此页面由 Cloud Translation API 翻译。

返回文件的特定字段

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

默认情况下，服务器会发回一组特定于要访问的资源的字段，已查询。例如，files.get 方法可能只返回 id、name 和 mimeType 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
  }
}

提取嵌套资源的字段

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

例如，如需检索 permissions 的 role 字段（嵌套资源），请使用以下任一选项：

将 permissions.get 替换为 fields=role 或 fields=*。
将 files.get 替换为 fields=permissions(role) 或 fields=permissions/role。
将 files.get 与 fields=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"
    }
  ]
}