Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

返回特定字段

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

如需返回所需的精确字段并提高性能，请在方法调用中使用 fields system 参数。

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

fields 参数的运作方式

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

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

对于 about、approvals、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)' 只会返回 permissions 数组中每个元素的权限 ID。
如需返回对象中的所有字段，请在字段选择中使用星号 (*) 作为通配符。例如，'permissions/permissionDetails/*' 会选择每个权限的所有可用权限详细信息字段。请注意，使用通配符可能会对请求的性能产生负面影响。
当映射的键包含特殊字符（例如正斜杠 / 或句点 .）时，您无法选择映射的各个元素。例如，尝试使用 fields=exportLinks/application/pdf 选择 exportLinks 中的特定导出格式键会产生 HTTP 400 Bad Request 错误，因为路径解析器会将 / 解释为嵌套属性分隔符。如需检索键中包含特殊字符的键值对，请请求整个映射（例如 fields=exportLinks），然后在客户端过滤结果。

请求

在此示例中，我们在请求中提供了文件 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、名称和嵌套的所有者详细信息（显示名称和电子邮件地址），同时检索下一页令牌以进行分页，请使用 fields=nextPageToken,files(id,name,owners(displayName,emailAddress)) 运行 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"
    }
  ]
}

替代系统形参

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