Graph API

Результаты с разбивкой на страницы

Структура и основные термины, связанные с API Graph, представлены в обзоре API Graph. В этом документе мы подробнее расскажем о результатах, возвращаемых запросами к API.

Отображение результатов с разбивкой на страницы

Как правило, при отправке запроса API к узлу или границе контекста вы не сможете получить все результаты этого запроса в одном ответе, поскольку количество возвращаемых объектов может достигать нескольких тысяч. Поэтому в большинстве ответов по умолчанию используется разбивка на страницы.

Разбивка на страницы по положению курсора

Разбивка на страницы по положению курсора — это самый эффективный способ, поэтому по возможности рекомендуется использовать именно его. Курсор указывает на случайным образом выбранную строку символов, которая отмечает определенный элемент в списке данных. Курсор всегда будет указывать на один и тот же элемент, однако при удалении этого элемента курсор становится недействительным. Поэтому приложения не должны сохранять старые курсоры или предполагать, что они будут действительны в будущем.

При чтении границы контекста, поддерживающей разбивку на страницы по положению курсора, выдается следующий ответ JSON:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

Граница контекста с разбивкой на страницы по положению курсора поддерживает следующие параметры:

  • before — курсор, указывающий на начало возвращенной страницы данных.
  • after — курсор, указывающий на конец возвращенной страницы данных.
  • limit — максимальное количество объектов, которое может вернуть запрос. Из-за фильтрации их может быть меньше, чем указано в параметре limit. Это не значит, что запрос дошел до конца списка данных. В этом случае вам нужно ориентироваться не на параметр limit, а на отсутствие параметра next, который описан ниже. Например, если вы задали для параметра limit значение 10 и запрос вернул 9 результатов, возможно, существует и десятый объект, но он отфильтрован по уровню конфиденциальности. Для некоторых границ контекста значение параметра limit совпадает с максимально допустимым. Это необходимо для повышения результативности.
  • next — конечная точка API Graph, которая возвращает следующую страницу данных. Если этого параметра нет, это последняя страница с данными. Поскольку на разбивку на страницы влияют настройки видимости и конфиденциальности, страница может быть пустой и содержать только ссылку next. Если ссылка next отсутствует, разбивку на страницы следует прекратить.
  • previous — конечная точка API Graph, которая возвращает предыдущую страницу данных. Если этого параметра нет в ответе, это значит, что возвращена первая страница данных.

Не храните курсоры. Они быстро становятся недействительными при добавлении или удалении элементов.

Разбивка на страницы по времени

Разбивка на страницы по времени предназначена для навигации по результатам с помощью меток времени Unix, указывающих на определенный момент времени в списке данных.

При обращении к конечной точке, которая использует разбивку на страницы по времени, вы получаете следующий ответ JSON:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/{your-user-id}/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/{your-user-id}/feed?limit=25&until=1364587774"
  }
}

Граница контекста с разбивкой на страницы по времени поддерживает следующие параметры:

  • until — метка времени Unix или значение данных strtotime, указывающее на конец диапазона данных, выбираемых по времени.
  • since — метка времени Unix или значение данных strtotime, указывающее на начало диапазона данных, выбираемых по времени.
  • limit — максимальное количество объектов, которое может вернуть запрос. Из-за фильтрации их может быть меньше, чем указано в параметре limit. Это не значит, что запрос дошел до конца списка данных. В этом случае вам нужно ориентироваться не на параметр limit, а на отсутствие параметра next, который описан ниже. Например, если вы задали для параметра limit значение 10 и запрос вернул 9 результатов, возможно, существует и десятый объект, но он отфильтрован по уровню конфиденциальности. Для некоторых границ контекста значение параметра limit совпадает с максимально допустимым. Это необходимо для повышения результативности.
  • next — конечная точка API Graph, которая возвращает следующую страницу данных.
  • previous — конечная точка API Graph, которая возвращает предыдущую страницу данных.

Чтобы получить непротиворечивые результаты, указывайте оба параметра: since и until. Не рекомендуется задавать разницу во времени более шести месяцев.

Разбивка на страницы по сдвигу

Разбивку на страницы по сдвигу можно использовать, если хронология не имеет значения и нужно просто получить определенное количество объектов. Используйте этот вариант только в том случае, если граница контекста не поддерживает разбивку на страницы по положению курсора или по времени.

Граница контекста с разбивкой на страницы по сдвигу поддерживает следующие параметры:

  • offset — сдвиг начала каждой страницы на указанное количество единиц.
  • limit — максимальное количество объектов, которое может вернуть запрос. Из-за фильтрации их может быть меньше, чем указано в параметре limit. Это не значит, что запрос дошел до конца списка данных. В этом случае вам нужно ориентироваться не на параметр limit, а на отсутствие параметра next, который описан ниже. Например, если вы задали для параметра limit значение 10 и запрос вернул 9 результатов, возможно, существует и десятый объект, но он отфильтрован по уровню конфиденциальности. Для некоторых границ контекста значение параметра limit совпадает с максимально допустимым. Это необходимо для повышения результативности.
  • next — конечная точка API Graph, которая возвращает следующую страницу данных. Если этого параметра нет, это последняя страница с данными. Поскольку на разбивку на страницы влияют настройки видимости и конфиденциальности, страница может быть пустой и содержать только ссылку next. Если ссылка next отсутствует, разбивку на страницы следует прекратить.
  • previous — конечная точка API Graph, которая возвращает предыдущую страницу данных. Если этого параметра нет в ответе, это значит, что возвращена первая страница данных.

Обратите внимание: при добавлении новых объектов в список, разбитый на страницы, содержимое каждой страницы изменяется.

Некоторые вызовы API не поддерживают разбивку на страницы по сдвигу. Чтобы получить непротиворечивые результаты, рекомендуем просматривать страницы с помощью ссылок previous и next, возвращенных в ответе на запрос.

К объектам, для которых возвращается много результатов (например, в случае объектов comments результаты могут исчисляться десятками тысяч), в процессе разбиения на страницы могут применяться ограничения. Когда приложение достигнет ограничения курсора, API вернет сообщение об ошибке:

{
  "error": {
    "message": "(#100) The After Cursor specified exceeds the max limit supported by this endpoint",
    "type": "OAuthException",
    "code": 100
  }
}

Дальнейшие действия

Теперь вы лучше познакомились с API Graph. Чтобы узнать больше об API Graph без написания кода, обратитесь к руководству по работе с Graph API Explorer. В разделе Стандартное использование вы найдете описание наиболее распространенных операций, а в разделе Использование с нашими SDK — список доступных SDK.