Изменение формы отклика с помощью параметров запросаUsing query parameters to change the shape of a response

API OneDrive предоставляет ряд необязательных параметров запросов, с помощью которых можно управлять тем, какие данные возвращаются в отклике.The OneDrive API provides several optional query parameters that can be used to control the specific data returned in a response.

В этом разделе:Covered in this topic:

Выбор свойствSelecting properties

С помощью параметра select строки запроса вы можете указать разделенный запятыми список свойств, возвращаемых для ресурсов Item.You can use the select query string parameter to provide a comma-separated list of properties to return on Items.

ПримерExample

В этом примере при получении дочерних элементов возвращаются только свойства name и size.This example selects only the name and size properties to be returned, when retrieving the children of an item.

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

Если отправить запрос со строкой select=name,size, в ответ будут включены только значения этих свойств. При использовании оператора select необходимо указывать все возвращаемые свойства.By submitting the request with the select=name,size query string, the objects in the response will only have those property values included. When using the select statement, you need to specify all properties to return in the statement.

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

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

Расширение коллекцийExpanding collections

В запросах API OneDrive дочерние коллекции не развертываются автоматически. Эта особенность позволяет уменьшить сетевой трафик и время создания ответа службой. Однако в некоторых случаях эти результаты может потребоваться включить в ответ.In OneDrive API requests, children collections of referenced items are not automatically expanded. This is by design because it reduces network traffic and the time it takes to generate a response from the service. However, in some cases you might want to include those results in a response.

Чтобы API OneDrive развернул дочернюю коллекцию и включил эти результаты, можно использовать параметр строки запроса expand.You can use the expand query string parameter to instruct the OneDrive API to expand a children collection and include those results.

Например, с помощью параметра expand можно получить сведения о корневом диске и элементах верхнего уровня на диске, как в приведенном ниже примере. Кроме того, в этом примере используется оператор select, чтобы возвращались только свойства id и name дочерних элементов.For example, to retrieve the root drive information and the top level items in a drive you use the expand parameter as in the example below. This example also uses a select statement to only return the id and name properties of the children items.

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

Запрос возвращает элементы коллекции с развернутой дочерней коллекцией.The request returns the collection items, with the children collection expanded.

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",
    }
  ]
}

Сортировка коллекцийSorting collections

С помощью строки запроса orderby вы можете управлять порядком сортировки элементов, возвращаемых из API OneDrive. Для коллекции элементов используйте перечисленные ниже поля в параметре orderby.You can use the orderby query string to control the sort order of the items returned from the OneDrive API. For a collection of items, use the following fields in the orderby parameter.

  • namename
  • sizesize
  • lastModifiedDateTimelastModifiedDateTime

Обратите внимание, что в OneDrive для бизнеса и SharePoint Server 2016 строка запроса orderby работает только со свойствами name и url.Note that in OneDrive for Business and SharePoint Server 2016, the orderby query string only works with name and url.

Чтобы отсортировать результаты по возрастанию или убыванию, добавьте asc или desc к имени поля, разделив их пробелом, например: ?orderby=name%20desc.To sort the results in ascending or descending order, append either asc or desc to the field name, separated by a space, for example, ?orderby=name%20desc.

Например, чтобы возвращалось содержимое корня диска в OneDrive, упорядоченное по убыванию размера, используйте следующий синтаксис: /drive/items/root/children?orderby=size%20desc.For example, to return the contents of the root of a drive in OneDrive, ordered largest to smallest, use this syntax: /drive/items/root/children?orderby=size%20desc.

Необязательные параметры запросов ODataOptional OData query parameters

Ниже представлена таблица необязательных параметров запросов OData, которые можно использовать в запросах к API OneDrive.Here is a table of optional OData query parameters you can use in your OneDrive API requests.

ИмяName ЗначениеValue СостояниеStatus ОписаниеDescription
expandexpand строкаstring доступенavailable Разделенный запятыми список отношений, развертываемых и включаемых в ответ. Например, чтобы получить дочерние элементы папки, используйте следующий синтаксис: expand=children.Comma-separated list of relationships to expand and include in the response. For example, to retrieve the children of a folder use expand=children.
selectselect строкаstring доступенavailable Разделенный запятыми список свойств, включаемых в ответ.Comma-separated list of properties to include in the response.
skipTokenskipToken строкаstring доступенavailable Токен разбиения на страницы, используемый для получения следующего набора результатов.Paging token that is used to get the next set of results.
toptop intint доступенavailable Количество элементов, возвращаемых в наборе результатов. В API OneDrive может действовать жесткое ограничение, не позволяющее запрашивать больше элементов в одном ответе.The number of items to return in a result set. The OneDrive API may have a hard limit that prevents you from asking for more items per response.
orderbyorderby строкаstring доступенavailable Разделенный запятыми список свойств, используемых для управления порядком элементов в коллекции ответа. Поддерживаются поля name, size и lastModifiedDateTime.Comma-separated list of properties that are used to sort the order of items in the response collection. Works for name, size, and lastModifiedDateTime fields.
filterfilter строкаstring недоступенnot available Строка фильтра, позволяющая отфильтровать ответ по набору условий.Filter string that lets you filter the response based on a set of criteria.

Примечание. В стандарте OData перед этими терминами добавляется префикс $. API OneDrive поддерживает использование этих параметров запросов как со специальным знаком, так и без него. Однако использование символа $ для этих аргументов должно быть согласованным в рамках запроса.Note: The OData standard prefixes these terms with a $. OneDrive API supports using these query parameters either with or without the special character, but you must be consistent throughout the request with your usage of the $ character on these arguments.