Penomoran halaman dengan $after di REST

Penomoran halaman mempersempit himpunan data besar ke halaman yang lebih kecil dan dapat dikelola. Di REST, Penyusun API Data (DAB) menggunakan $after parameter kueri untuk paginasi keyset, menyediakan traversal yang stabil dan efisien melalui hasil yang diurutkan. Setiap token menandai posisi rekaman terakhir dari halaman sebelumnya, memungkinkan permintaan berikutnya berlanjut dari titik tersebut. Tidak seperti penomoran halaman offset, paginasi set kunci mencegah baris yang hilang atau diduplikasi saat data berubah di antara permintaan.

Buka versi GraphQL dokumen ini.

Sekilas

Konsep	Description
$after	Token kelanjutan buram yang dikembalikan dari permintaan sebelumnya
$first	Jumlah maksimum rekaman yang diambil per halaman
nextLink	URL untuk halaman berikutnya mencakup $after

Penomoran halaman dasar

Dalam contoh ini, kita mendapatkan tiga buku pertama.

Permintaan HTTP

GET /api/books?$first=3

SQL Konseptual

SELECT TOP (3)
  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" }
  ],
  "nextLink": "/api/books?$first=3&$after=eyJpZCI6M30="
}

Nota

Jika next-link-relative=true dalam konfigurasi, nextLink berisi jalur relatif; jika tidak, itu adalah URL absolut.

Kelanjutan dengan $after

Parameter $after menentukan token kelanjutan untuk halaman berikutnya. Nilainya adalah string yang dikodekan base64 yang mewakili rekaman terakhir halaman sebelumnya.

Peringatan

$after membawa token buram yang mengidentifikasi tempat halaman terakhir berakhir. Perlakukan token sebagai tidak dapat diubah dan jangan pernah mencoba membangun atau memodifikasinya.

Dalam contoh ini, kita mendapatkan tiga buku berikutnya setelah token halaman terakhir.

Permintaan HTTP

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

SQL Konseptual

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

Contoh tanggapan

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

Akhir data

Ketika nextLink tidak ada, tidak ada lagi catatan untuk diambil. Respons halaman akhir hanya value menyertakan array tanpa nextLink.

Contoh tanggapan

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

Nota

Setiap skema atau perubahan urutan membatalkan token yang dikeluarkan sebelumnya. Klien harus memulai ulang penomoran halaman dari halaman pertama.

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.