返回特定字段

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

如需返回您需要的确切字段并提升性能，请在方法调用中使用 fields system parameter。

如需了解适用于 Drive API 的其他系统参数，请参阅替代系统参数。

fields 参数的工作方式

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

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

对于 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.”错误。此示例的正确字段参数为 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.get，并使用 fields=role。
permissions.get，并使用 fields=* 显示所有 permissions 字段。
files.get，并使用 fields=permissions(role) 或 fields=permissions/role。
files.get，并使用 fields=permissions 显示所有 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"
    }
  ]
}

替代系统参数

系统参数中记录了适用于所有 Google Drive API 操作的查询参数。