Limitation de la taille de page avec $first dans REST

La limitation de la taille de page empêche les clients ou serveurs d’accablants lors de l’interrogation de jeux de données volumineux. Dans REST, le générateur d’API de données (DAB) utilise le paramètre pour contrôler le $first nombre d’enregistrements retournés dans une seule réponse. DAB applique la pagination basée sur le curseur en interne, mais $first peut être utilisée même lorsque la continuation n’est pas nécessaire.

Note

$first limite le nombre de lignes retournées, mais ne gère pas elle-même la continuation. Pour plusieurs pages, utilisez $after.

Accédez à la version GraphQL de ce document.

Aperçu

Concept	Descriptif
Taille de page par défaut	runtime.pagination.default-page-size (valeur par défaut : 100)
Taille maximale de la page	runtime.pagination.max-page-size (valeur par défaut : 100000)
Remplacement du client	$first
Demande maximale	$first=-1 demande la taille maximale de page configurée

Si $first elle est omise, la taille de page par défaut s’applique automatiquement.

Modèle d’utilisation

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

Example

Limitez les résultats à cinq livres.

GET /api/books?$first=5

SQL conceptuel

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

Exemple de réponse

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

Règles de validation

Input	Résultat
Omis	Utilise default-page-size
Entier positif ≤ max	Accepté
-1	Étendue à max-page-size
0	400 (non valide)
< -1	400
> max-page-size	400

Exemple de message d’erreur

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

Exemple de configuration

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

Voir aussi

Concept	REST	GraphQL	Objectif
Projection	$select	Éléments	Choisir les champs à retourner
Filtrage	$filter	filtre	Restreindre les lignes par condition
Tri	$orderby	orderBy	Définir l’ordre de tri
Taille de la page	$first	first	Limiter le nombre d’éléments par page
Continuation	$after	après	Continuer à partir de la dernière page à l’aide d’un curseur

Note

Les mots clés REST commencent par $les conventions OData suivantes.