Разбиение на страницы с помощью $after REST

Разбивка на страницы сужает большие наборы данных на небольшие управляемые страницы. В REST построитель API данных (DAB) использует $after параметр запроса для разбиения на страницы набора ключей, обеспечивая стабильный и эффективный обход с помощью упорядоченных результатов. Каждый маркер помечает позицию последней записи с предыдущей страницы, позволяя следующему запросу продолжаться с этой точки. В отличие от смещения разбиения на страницы, набор ключей предотвращает отсутствие или дубликаты строк при изменении данных между запросами.

Перейдите к версии GraphQL этого документа.

Краткий обзор

Понятие	Description
$after	Непрозрачный маркер продолжения, возвращенный из предыдущего запроса
$first	Максимальное количество записей для получения каждой страницы
nextLink	URL-адрес следующей страницы включает $after

Базовая разбивка на страницы

В этом примере мы получаем первые три книги.

HTTP-запрос

GET /api/books?$first=3

Концептуальный SQL

SELECT TOP (3)
  id,
  sku_title AS title
FROM dbo.books
ORDER BY id ASC;

Пример ответа

{
  "value": [
    { "id": 1, "title": "Dune" },
    { "id": 2, "title": "Foundation" },
    { "id": 3, "title": "Hyperion" }
  ],
  "nextLink": "/api/books?$first=3&$after=eyJpZCI6M30="
}

Замечание

Если next-link-relative=true в конфигурации содержит nextLink относительный путь; в противном случае это абсолютный URL-адрес.

Продолжение с $after

Параметр $after задает маркер продолжения для следующей страницы. Значение представляет собой строку в кодировке Base64, представляющую последнюю запись предыдущей страницы.

Предупреждение

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

В этом примере мы получаем следующие три книги после маркера последней страницы.

HTTP-запрос

GET /api/books?$first=3&$after=eyJpZCI6M30=

Концептуальный SQL

SELECT TOP (3)
  id,
  sku_title AS title
FROM dbo.books
WHERE id > 3
ORDER BY id ASC;

Пример ответа

{
  "value": [
    { "id": 4, "title": "I, Robot" },
    { "id": 5, "title": "The Left Hand of Darkness" },
    { "id": 6, "title": "The Martian" }
  ],
  "nextLink": "/api/books?$first=3&$after=eyJpZCI6Nn0="
}

Конец данных

Если nextLink нет, для получения записей больше нет. Окончательный value ответ страницы включает только массив без nextLink.

Пример ответа

{
  "value": [
    { "id": 7, "title": "Rendezvous with Rama" },
    { "id": 8, "title": "The Dispossessed" }
  ]
}

Замечание

Любая схема или изменение порядка делает недействительными ранее выданные маркеры. Клиенты должны перезапустить разбиение на страницы с первой страницы.

Пример конфигурации

{
  "runtime": {
    "pagination": {
      "default-page-size": 100,
      "max-page-size": 100000
    }
  },
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.books"
      },
      "mappings": {
        "sku_title": "title",
        "sku_price": "price"
      },
      "relationships": {
        "book_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      }
    },
    "Category": {
      "source": {
        "type": "table",
        "object": "dbo.categories"
      },
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

См. также

Понятие	REST	GraphQL	Цель
Projection	$select	items	Выбор возвращаемых полей
Filtering	$filter	фильтр	Ограничение строк по условию
Сортировка	$orderby	orderBy	Определение порядка сортировки
Размер страницы	$first	first	Ограничение количества элементов на страницу
Продолжение	$after	после	Продолжить с последней страницы с помощью курсора

Замечание

Ключевые слова REST начинаются с $следующих соглашений OData.