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.

  2. Ensuite, vous pouvez afficher les pages suivantes avec des requêtes contenant le paramètre FirstItem ou NextPageToken, dépendamment de la méthode.

L’API OUTSCALE a deux systèmes de pagination, dépendamment de la méthode utilisée :

  • Les méthodes de l’API OUTSCALE concernant les politiques, les utilisateurs et les groupes d’utilisateurs utilisent les paramètres ResultsPerPage et FirstItem.

  • Les autres méthodes de l’API OUTSCALE utilisent les paramètres ResultsPerPage et NextPageToken.

La plupart des requêtes API de lecture 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 OUTSCALE, 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.

  • La requête utilise une méthode qui concerne les politiques, les utilisateurs et les groupes d’utilisateurs, qui utilise un système de pagination différent.

Les résultats d’une requête paginée avec ce paramètre sont organisés par ordre de date de création et d’ID.

Paramètre FirstItem

Si vous utilisez le paramètre ResultsPerPage dans une requête API OUTSCALE qui concerne les politiques, les utilisateurs et les groupes d’utilisateurs, vous devez ensuite utiliser le paramètre FirstItem dans pour afficher les pages de résultats suivantes.

Une requête de lecture renvoie une liste d’objets. Le paramètre ResultsPerPage divise cette liste en plusieurs listes plus petites, ou pages, plus facile à analyser. Le paramètre FirstItem représente le nombre ordinal du premier élément de la liste, ou page, que vous voulez afficher. Cela veut dire que le paramètre FirstItem n’est pas renvoyé par chaque requête. Vous devez l’incrémenter manuellement en conséquence.

Les résultats d’une requête paginée avec ce paramètre sont organisés par ordre d’ID.

Exemples de cas d’utilisation

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.

Paginer la réponse de la méthode ReadUserGroups

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

Pour cet exemple, le compte faisant la requête ReadUserGroups a cinq groupes d’utilisateurs et souhaite afficher pas plus de deux résultats par page.

Lancer une requête paginée

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

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

La méthode renvoie une liste de vos deux premiers groupes d’utilisateurs. La réponse indique également si plus d’éléments peuvent être renvoyés par la requête via le paramètre HasMoreItems. De plus, la réponse affiche aussi des informations complémentaires sur le nombre maximum de résultats pouvant être renvoyés par la requête, et si la taille de la page est plus grande qu’autorisé, via les paramètres MaxResultsLimit et MaxResultsTruncated, respectivement.

Exemple de résultat
{
    "UserGroups": [
        {
            "UserGroupId": "123456ABCDEF",
            "Path": "/",
            "CreationDate": "2024-05-27T13:50:36.000+0000",
            "LastModificationDate": "2024-05-27T13:50:36.000+0000",
            "Name": "Group5",
            "Orn": "orn:ows:idauth::123456789:group/Group5"
        },
        {
            "UserGroupId": "56789GHIJKL",
            "Path": "/",
            "CreationDate": "2024-05-27T13:50:29.000+0000",
            "LastModificationDate": "2024-05-27T13:50:29.000+0000",
            "Name": "Group3",
            "Orn": "orn:ows:idauth::123456789:group/Group3"
        }
    ],
    "HasMoreItems": true,
    "ResponseContext": {
        "RequestId": "9cc405d5-3013-4996-9a38-5779daf72a51"
    },
    "MaxResultsLimit": 100,
    "MaxResultsTruncated": false

}

Afficher la page suivante

Pour afficher la page suivante, utilisez la requête initiale et le paramètre FirstItem. Le paramètre FirstItem est l’élément qui commence la liste demandée des groupes d’utilisateurs. Sa valeur doit être le numéro ordinal qui suit le dernier résultat de la liste renvoyée lors de l’itération précédente. Dans notre cas, la valeur de FirstItem devrait être 2.

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

La réponse montre la page suivante qui contient les deux éléments suivants de la liste.

Exemple de résultat
{
    "UserGroups": [
        {
            "UserGroupId": "123456GHIJKL",
            "Path": "/",
            "CreationDate": "2024-05-27T13:50:18.000+0000",
            "LastModificationDate": "2024-05-27T13:50:18.000+0000",
            "Name": "Group1",
            "Orn": "orn:ows:idauth::123456789:group/Group1"
        },
        {
            "UserGroupId": "56789ABCDEF",
            "Path": "/",
            "CreationDate": "2024-05-27T13:50:33.000+0000",
            "LastModificationDate": "2024-05-27T13:50:33.000+0000",
            "Name": "Group4",
            "Orn": "orn:ows:idauth::123456789:group/Group4"
        }
    ],
    "HasMoreItems": true,
    "ResponseContext": {
        "RequestId": "7606fac7-f6b5-4822-ab1b-9d9da5fa3287"
    },
    "MaxResultsLimit": 100,
    "MaxResultsTruncated": false
}

Sur cette deuxième page, le paramètre HasMoreItems indique qu’il y a encore des éléments à afficher. Pour afficher le dernier élément de la liste, répétez l’étape précédente tout en incrémentant le paramètre FirstItem en conséquence.

Exemple de requête
$ osc-cli api ReadUserGroups \
    --ResultsPerPage 2
    --FirstItem 4

Le résultat montre la dernière page qui contient le dernier élément de la liste.

Exemple de résultat
{
    "UserGroups": [
        {
            "UserGroupId": "02468ABCDEF",
            "Path": "/",
            "CreationDate": "2024-05-27T13:50:24.000+0000",
            "LastModificationDate": "2024-05-27T13:50:24.000+0000",
            "Name": "Group2",
            "Orn": "orn:ows:idauth::123456789:group/Group2"
        }
    ],
    "HasMoreItems": false,
    "ResponseContext": {
        "RequestId": "b36c837a-fa7b-486f-89d8-971b880eccc4"
    },
    "MaxResultsLimit": 100,
    "MaxResultsTruncated": false
}

À ce stade, tous les résultats ont été affichés, le paramètre HasMoreItems a pour valeur false.

Exporter en PDF