返回特定字段

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

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

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

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.”的错误。此示例的正确字段参数为 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"
    }
  ]
}

替代系统形参

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