通过

使用查询参数更改响应的形状

  • 项目

OneDrive API 提供了多个可选查询参数，可用于控制响应中返回的具体数据。

本主题将介绍：

选择属性

可使用参数选择 ， 字符串参数，提供以逗号分隔的属性列表，返回值 返回。

示例

此示例在检索项的子项时，仅选择要返回的 name 和 size 属性。

GET /drive/root/children?select=name,size

使用 select=name,size 查询字符串提交请求，响应中的对象只会包含这些属性值。 使用 select 语句时，需要在语句中指定要要返回的所有属性。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": [
    {
      "id": "13140a9sd9aba",
      "name": "Documents",
      "size": 1024
    },
    {
      "id": "123901909124a",
      "name": "Pictures",
      "size": 1012010210
    }
  ]
}

扩展集合

在 OneDrive API 请求中，引用项的子项集合不会自动扩展。 这是有意为之，因为这样可以减少网络流量以及生成服务响应所需的时间。 不过，在某些情况下，建议在响应中添加这些结果。

可以使用 expand 查询字符串参数，指示 OneDrive API 扩展子项集合，并添加这些结果。

例如，若要检索根驱动器信息和驱动器中的顶级项，请使用 expand 参数，如以下示例所示。 此示例还使用 select 语句，以便仅返回子项的 id 和 name 属性。

GET /drive/root?expand=children(select=id,name)

请求返回集合项，其中子项集合已扩展。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "12312312541",
  "name": "root",
  "size": 218753122201,
  "webUrl": "https://onedrive.live.com/?cid=0f040...",
  "folder": {
    "childCount": 4
  },
  "children": [
    {
      "id": "F04AA961744A809!48443",
      "name": "Applications",
    },
    {
      "id": "F04AA961744A809!92647",
      "name": "Attachments",
    },
    {
      "id": "F04AA961744A809!93269",
      "name": "Balsmiq Sketches",
    },
    {
      "id": "F04AA961744A809!65191",
      "name": "Camera imports",
    }
  ]
}

集合排序

可以使用 orderby 查询字符串，控制 OneDrive API 返回的项的排序顺序。 对于项集合，请在 orderby 参数中使用以下字段。

  • name
  • size
  • lastModifiedDateTime

请注意，在 OneDrive for Business 和 SharePoint Server 2016 中，orderby 查询字符串仅支持 name 和 url。

若要以升序或降序排列结果，请在字段名称中分别追加 asc 或 desc（用空格隔开）。例如，?orderby=name%20desc。

例如，若要返回 OneDrive 中驱动器的根内容，并按从大到小的顺序排列，请使用以下语法：/drive/items/root/children?orderby=size%20desc。

OData 可选查询参数

下表列出了可以在 OneDrive API 请求中使用的可选 OData 查询参数。

名称 值 状态 说明
expand string 可用 要在响应中扩展和添加的关系列表（以逗号分隔）。 例如，若要检索文件夹的子项，请使用 expand=children。
select string 可用 要在响应中添加的属性列表（以逗号分隔）。
skipToken string 可用 用于获取下一组结果的分页令牌。
top int 可用 结果集中要返回的项数。 OneDrive API 可能会设定硬性上限，以阻止你请求每个响应返回过多项。
orderby string 可用 用于在响应集合中对项进行排序的属性列表（以逗号分隔）。 支持 name、size 和 lastModifiedDateTime 字段。
filter string 不适用 可以根据一系列条件筛选响应的筛选字符串。

注意：根据 OData 标准，需要在这些词前面加上 $ 前缀。 虽然 OneDrive API 支持使用这些查询参数，不管带不带特殊字符，但必须在整个请求中对这些参数一致使用 $ 字符。