返回特定字段

如需返回所需的确切字段并提升性能，请在方法调用中使用 fields 系统参数。

本文档介绍了如何在 Google 云端硬盘中使用 fields 参数。

fields 参数的运作方式

fields 参数使用 FieldMask 进行响应过滤。字段掩码用于指定请求应返回的部分字段。使用字段掩码是一种良好的设计做法，可确保您不会请求不必要的数据，这有助于避免产生不必要的处理时间。

如果您未指定 fields 参数，服务器将返回一组特定于该方法的默认字段。例如，files 方法上的 list 方法仅会返回 kind、id、name 和 mimeType 字段。permissions 资源上的 get 方法会返回另一组默认字段。

对于 about、comments（不包括 delete）和 replies（不包括 delete）资源的所有方法，您必须设置 fields 参数。这些方法不会返回一组默认字段。

处理完含有 fields 参数的有效请求之后，服务器将返回一个 HTTP 200 OK 状态代码以及所请求的数据。如果 fields 参数出现错误或因其他原因而无效，服务器将返回 HTTP 400 Bad Request 状态代码以及一条错误消息，说明您的字段选择出现了什么错误。例如，files.list(fields='files(id,capabilities,canAddChildren)') 会导致“Invalid field selection canAddChildren”错误。此示例的正确 fields 参数为 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 数组中每个元素的权限 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 字段（嵌套资源），请使用以下任一选项：

  • 使用 fields=role 调用 permissions.get。
  • 将 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"
    }
  ]
}