Sidnumrering med $after i REST

Sidnumrering begränsar stora datamängder till mindre, hanterbara sidor. I REST använder $after Data API Builder (DAB) frågeparametern för nyckeluppsättningsnumrering, vilket ger stabil och effektiv bläddring genom ordnade resultat. Varje token markerar positionen för den sista posten från föregående sida, vilket gör att nästa begäran kan fortsätta från den punkten. Till skillnad från offset-sidnumrering förhindrar sidnumrering av nyckeluppsättningar saknade eller duplicerade rader när data ändras mellan begäranden.

Gå till GraphQL-versionen av det här dokumentet.

Snabbblick

Begrepp	Description
$after	Den täckande fortsättningstoken som returnerades från den tidigare begäran
$first	Det maximala antalet poster som ska hämtas per sida
nextLink	URL för nästa sida innehåller $after

Grundläggande sidnumrering

I det här exemplet får vi de tre första böckerna.

HTTP-begäran

GET /api/books?$first=3

Konceptuell SQL

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

Exempelsvar

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

Anmärkning

Om next-link-relative=true i konfigurationen, nextLink innehåller en relativ sökväg, annars är det en absolut URL.

Fortsättning med $after

Parametern $after anger fortsättningstoken för nästa sida. Värdet är en base64-kodad sträng som representerar den sista posten på föregående sida.

Varning

$after bär en ogenomskinlig token som identifierar var den sista sidan slutade. Behandla token som oföränderliga och försök aldrig att konstruera eller ändra dem.

I det här exemplet får vi nästa tre böcker efter den sista sidans token.

HTTP-begäran

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

Konceptuell SQL

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

Exempelsvar

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

Slut på data

När nextLink saknas finns det inga fler poster att hämta. Det sista sidsvaret innehåller endast en value matris utan .nextLink

Exempelsvar

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

Anmärkning

Alla schema- eller beställningsändringar ogiltigförklarar tidigare utfärdade token. Klienter måste starta om sidnumreringen från den första sidan.

Exempelkonfiguration

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

Se även

Begrepp	REST	GraphQL	Avsikt
Projection	$select	items	Välj vilka fält som ska returneras
Filtering	$filter	filtrera	Begränsa rader efter villkor
Sortering	$orderby	orderBy	Definiera sorteringsordningen
Sidstorlek	$first	first	Begränsa antalet objekt per sida
Fortsättning	$after	efter	Fortsätt från den sista sidan med hjälp av en markör

Anmärkning

REST-nyckelord börjar med $, enligt OData-konventioner.