Ограничение размера страницы в $first REST

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

Замечание

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

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

Обзор

Понятие	Description
Размер страницы по умолчанию	runtime.pagination.default-page-size (по умолчанию — 100)
Максимальный размер страницы	runtime.pagination.max-page-size (по умолчанию — 100000)
Переопределение клиента	$first
Максимальное количество запросов	$first=-1 запрашивает настроенный максимальный размер страницы

Если $first опущен, размер страницы по умолчанию применяется автоматически.

Шаблон использования

GET /api/{entity}?$first=N

Example

Ограничить результаты пятью книгами.

GET /api/books?$first=5

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

SELECT TOP (5)
  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" },
    { "id": 4, "title": "I, Robot" },
    { "id": 5, "title": "The Martian" }
  ]
}

Правила проверки

Ввод	Result
Упущенный	Использует default-page-size
Максимальное число положительного целого числа ≤	Принято
-1	Развернуто в max-page-size
0	400 (недопустимо)
< -1	400
> max-page-size	400

Пример сообщения об ошибке

Invalid number of items requested, first argument must be either -1 or a positive number within the max page size limit of 100000. Actual value: 0

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

{
  "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.