Membatasi ukuran halaman dengan $first di REST

Membatasi ukuran halaman mencegah klien atau server yang luar biasa saat mengkueri himpunan data besar. Di REST, Penyusun API Data (DAB) menggunakan $first parameter untuk mengontrol berapa banyak rekaman yang dikembalikan dalam satu respons. DAB menerapkan paginasi berbasis kursor secara internal, tetapi $first dapat digunakan bahkan ketika kelanjutan tidak diperlukan.

Nota

$first membatasi jumlah baris yang dikembalikan tetapi tidak menangani kelanjutan. Untuk beberapa halaman, gunakan $after.

Buka versi GraphQL dokumen ini.

Gambaran Umum

Konsep	Description
Ukuran halaman bawaan	runtime.pagination.default-page-size (default ke 100)
Ukuran halaman maks	runtime.pagination.max-page-size (default ke 100000)
Penimpaan klien	$first
Meminta maks	$first=-1 meminta ukuran halaman maks yang dikonfigurasi

Jika $first dihilangkan, ukuran halaman default berlaku secara otomatis.

Pola penggunaan

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

Example

Batasi hasilnya hingga lima buku.

GET /api/books?$first=5

SQL Konseptual

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

Contoh tanggapan

{
  "value": [
    { "id": 1, "title": "Dune" },
    { "id": 2, "title": "Foundation" },
    { "id": 3, "title": "Hyperion" },
    { "id": 4, "title": "I, Robot" },
    { "id": 5, "title": "The Martian" }
  ]
}

Aturan validasi

Masukan	Result
Dihilangkan	Menggunakan default-page-size
Bilangan bulat positif ≤ maks	Diterima
-1	Diperluas ke max-page-size
0	400 (tidak valid)
< -1	400
> max-page-size	400

Contoh pesan kesalahan

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

Konfigurasi contoh

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

Lihat juga

Konsep	REST	GraphQL	Tujuan
Projection	$select	items	Pilih bidang mana yang akan dikembalikan
Penyaringan	$filter	saringan	Membatasi baris menurut kondisi
Pengurutan	$orderby	orderBy	Tentukan urutan pengurutan
Ukuran halaman	$first	first	Membatasi jumlah item per halaman
Kelanjutan	$after	sesudah	Lanjutkan dari halaman terakhir menggunakan kursor

Nota

Kata kunci REST dimulai dengan $, mengikuti konvensi OData.