Tutoriel : Paginer une requête API

Les requêtes API peuvent renvoyer une grande quantité de données. La pagination d’une requête consiste à renvoyer sa réponse en plus petits sous-ensembles de données ou de pages plus faciles à lire ou à manipuler, plutôt que de renvoyer l’ensemble des données en une seule réponse.

La pagination d’une requête peut améliorer de manière significative :

  • Les performances : Le renvoi d’un grand ensemble de données en une seule réponse peut être lent et consommateur en ressources. En paginant un résultat en sous-ensembles de données plus petits, l’API peut renvoyer les données plus rapidement et avec moins de ressources.

  • La gestion de la mémoire : Le traitement d’un grand ensemble de données peut nécessiter beaucoup de mémoire. Grâce aux réponses paginées, la quantité de données à stocker en mémoire pour vos outils est réduite.

Informations générales

La pagination du résultat d’une requête est une procédure en deux étapes :

  1. Vous devez d’abord lancer une requête avec un nombre limité de résultats par page via le paramètre ResultsPerPage.

  2. Ensuite, vous pouvez afficher les pages suivantes avec des requêtes contenant le paramètre NextPageToken.

Les résultats d’une requête paginée sont triés par ordre croissant de date de création et d’ID.

La plupart des requêtes API peuvent être paginées. Pour en savoir plus, voir nos documentations API.

Paramètre NextPageToken

Si vous avez utilisé le paramètre ResultsPerPage dans une requête API, le paramètre NextPageToken est renvoyé dans la réponse. Ce paramètre est renvoyé jusqu’à ce qu’il n’y ait plus de résultats à afficher.

Le paramètre NextPageToken n’est pas renvoyé lorsque :

  • Il n’y a qu’un seul résultat.

  • ResultsPerPage est supérieur au nombre total de résultats. Dans ce cas, tous les résultats sont renvoyés sur une seule page.

Paginer la réponse de la méthode ReadSnapshots

Ce tutoriel montre un exemple de pagination de la réponse de la méthode API OUTSCALE ReadSnapshots

Pour cet exemple, le compte faisant la requête ReadSnapshots a trois snapshots et souhaite afficher deux résultats par page.

Lancer une requête paginée

Utilisez la méthode ReadSnapshots avec le paramètre ResultsPerPage à deux résultats par page.

Exemple de requête
$ osc-cli api ReadSnapshots \
    --ResultsPerPage 2

Le résultat affiche les informations de deux snapshots and le paramètre NextPageToken.

Exemple de résultat
{
  "Snapshots": [
    {
      "VolumeSize": 10,
      "AccountId": "123456789012",
      "VolumeId": "vol-12345678",
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "PermissionsToCreateVolume": {
        "GlobalPermission": false,
        "AccountIds": []
      },
      "Progress": 100,
      "SnapshotId": "snap-12345678",
      "State": "completed",
      "Description": "Snapshot created from a volume",
      "Tags": []
    },
    {
      "VolumeSize": 10,
      "AccountId": "123456789012",
      "VolumeId": "vol-87654321",
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "PermissionsToCreateVolume": {
        "GlobalPermission": false,
        "AccountIds": []
      },
      "Progress": 100,
      "SnapshotId": "snap-12345679",
      "State": "completed",
      "Description": "Test snapshot",
      "Tags": []
    },
  ],
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  }
  "NextPageToken": "YOUR_NEXT_PAGE_TOKEN"
}

Afficher la page suivante

Utilisez la requête initiale et le paramètre NextPageToken renvoyé dans la réponse précédente pour afficher la page suivante.

Si vous modifiez un paramètre de la requête initiale, par exemple le nombre de résultats par page, une nouvelle requête est créée et les résultats sont affichés depuis le début.

Exemple de requête
$ osc-cli api ReadSnapshots \
    --ResultsPerPage 2
    --NextPageToken "YOUR_NEXT_PAGE_TOKEN"

Le résultat affiche la page suivante.

Exemple de résultat
{
  "Snapshots": [
    {
      "VolumeSize": 10,
      "AccountId": "123456789012",
      "VolumeId": "vol-12345678",
      "CreationDate": "2010-10-02T12:34:56.789Z",
      "PermissionsToCreateVolume": {
        "GlobalPermission": false,
        "AccountIds": []
      },
      "Progress": 100,
      "SnapshotId": "snap-12345679",
      "State": "completed",
      "Description": "Snapshot created from a volume",
      "Tags": []
    }
  ],
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  }
}

Sur cette deuxième page, le résultat affiche le dernier snapshot. Comme tous les résultats ont été affichés, la réponse n’inclut pas le paramètre NextPageToken.