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

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

本主题将介绍:

选择属性

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

示例

此示例在检索项的子项时,仅选择要返回的 namesize 属性。

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 语句,以便仅返回子项的 idname 属性。

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 参数中使用以下字段。

  • 名称
  • size
  • lastModifiedDateTime

请注意,在 OneDrive for Business 和 SharePoint Server 2016 中,orderby 查询字符串仅支持 nameurl

若要以升序或降序排列结果,请在字段名称中分别追加 ascdesc(用空格隔开)。例如,?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 可用 用于在响应集合中对项进行排序的属性列表(以逗号分隔)。支持 namesizelastModifiedDateTime 字段。
filter string 不适用 可以根据一系列条件筛选响应的筛选字符串。

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