Impaginazione con $after in REST

La paginazione restringe i set di dati di grandi dimensioni a pagine più piccole e gestibili. In REST, Data API Builder (DAB) usa il parametro di query per l'impaginazione$after keyset, fornendo un attraversamento stabile ed efficiente tramite risultati ordinati. Ogni token contrassegna la posizione dell'ultimo record della pagina precedente, consentendo alla richiesta successiva di continuare da quel punto. A differenza della paginazione offset, la paginazione keyset impedisce righe mancanti o duplicate quando i dati cambiano tra le richieste.

Passare alla versione GraphQL di questo documento.

Sguardo rapido

Concetto	Description
$after	Token di continuazione opaco restituito dalla richiesta precedente
$first	Numero massimo di record da recuperare per pagina
nextLink	L'URL della pagina successiva include $after

Paginazione di base

In questo esempio si ottengono i primi tre libri.

Richiesta HTTP

GET /api/books?$first=3

SQL concettuale

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

Risposta di esempio

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

Annotazioni

Se next-link-relative=true nella configurazione contiene nextLink un percorso relativo; in caso contrario, si tratta di un URL assoluto.

Continuazione con $after

Il $after parametro specifica il token di continuazione per la pagina successiva. Il valore è una stringa con codifica Base64 che rappresenta l'ultimo record della pagina precedente.

Avvertimento

$after contiene un token opaco che identifica dove è terminata l'ultima pagina. Considerare i token come non modificabili e non tentare mai di crearli o modificarli.

In questo esempio si ottengono i tre libri successivi dopo il token dell'ultima pagina.

Richiesta HTTP

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

SQL concettuale

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

Risposta di esempio

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

Fine dei dati

Quando nextLink è assente, non ci sono più record da recuperare. La risposta della pagina finale include solo una value matrice senza un oggetto nextLink.

Risposta di esempio

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

Annotazioni

Qualsiasi modifica dello schema o dell'ordinamento invalida i token rilasciati in precedenza. I client devono riavviare la paginazione dalla prima pagina.

Configurazione di esempio

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

Vedere anche

Concetto	REST	GraphQL	Scopo
Projection	$select	Elementi	Scegliere i campi da restituire
Filtraggio	$filter	filtro	Limitare le righe per condizione
Ordinamento	$orderby	orderBy	Definire l'ordinamento
Dimensioni pagina	$first	primo	Limitare il numero di elementi per pagina
Continuazione	$after	dopo	Continuare dall'ultima pagina usando un cursore

Annotazioni

Le parole chiave REST iniziano con $, seguendo le convenzioni OData.