Résultats paginés

Nous abordons les notions de base de la terminologie et de la structure de l’API Graph dans la présentation de l’API Graph. Ce document aborde plus en détail les résultats de vos requêtes d’API.

Défilement des résultats paginés

Lorsque vous adressez une demande d’API à un nœud ou à une arête, vous ne recevez généralement pas tous les résultats de cette demande dans une seule réponse. Cela est dû au fait que certaines réponses peuvent contenir des milliers d’objets. La plupart des réponses sont donc paginées par défaut.

Pagination en fonction de curseurs

La pagination en fonction de curseurs est la méthode de pagination la plus efficace et devrait toujours être utilisée lorsque cela est possible. Un curseur fait référence à une chaîne de caractères aléatoire qui marque un élément particulier dans une liste de données. Le curseur, qui désignera toujours l’élément, ne sera plus valide si ce dernier est supprimé ou effacé. Votre application ne doit donc pas stocker de curseurs ou supposer qu’ils resteront valides à l’avenir.

Lors de la lecture d’une arête prenant en charge la pagination avec curseurs, la réponse JSON suivante s’affiche :

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

Une arête paginée à l’aide de curseurs prend en charge les paramètres suivants :

• before : curseur qui désigne le début de la page de données renvoyée.
• after : curseur qui désigne la fin de la page de données renvoyée.
• limit : nombre maximum d’objets pouvant être renvoyés. Une requête peut renvoyer moins d’objets que la valeur limit en raison d’un filtrage. N’attendez pas que le nombre de résultats soit inférieur à la valeur limit, utilisez plutôt l’absence de next comme décrit ci-dessous, pour indiquer que votre requête a atteint la fin de la liste de données. Par exemple, si vous définissez une limit sur 10 et que vous obtenez 9 résultats, d’autres données peuvent être disponibles, mais un élément a été supprimé en raison d’un filtre de confidentialité. Certaines arêtes peuvent aussi comporter une limite maximale pour la valeur limit pour des raisons de performance. Dans tous les cas, l’API renvoie les liens de pagination corrects.
• next : point de terminaison de l’API Graph qui renvoie la page de données suivante. S’il n’est pas inclus, il s’agit de la dernière page de données. En raison du fonctionnement de la pagination par rapport à la visibilité et à la confidentialité, une page peut à la fois être vide et contenir un lien de pagination next. Cessez la pagination lorsque le lien next n’apparaît plus.
• previous : point de terminaison de l’API Graph qui renvoie la page de données précédente. S’il n’est pas inclus, il s’agit de la première page de données.

Pagination en fonction du temps

La pagination en fonction du temps est utilisée pour parcourir les résultats de données à l’aide d’horodatages Unix qui désignent des heures particulières dans une liste de données.

Lorsque vous utilisez un point de terminaison qui a recours à une pagination en fonction du temps, la réponse JSON suivante s’affiche :

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/{your-user-id}/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/{your-user-id}/feed?limit=25&until=1364587774"
  }
}

Une arête paginée en fonction du temps prend en charge les paramètres suivants :

• until : horodatage Unix ou valeur de données strtotime qui désigne la fin de la plage de données temporelles.
• since : horodatage Unix ou valeur de données strtotime qui désigne le début de la plage de données temporelles.
• limit : nombre maximum d’objets pouvant être renvoyés. Une requête peut renvoyer moins d’objets que la valeur limit en raison d’un filtrage. N’attendez pas que le nombre de résultats soit inférieur à la valeur limit pour indiquer que votre requête a atteint la fin de la liste de données, mais utilisez plutôt l’absence de next comme décrit ci-dessous. Par exemple, si vous définissez une limit sur 10 et que vous obtenez 9 résultats, d’autres données peuvent être disponibles, mais un élément a été supprimé en raison d’un filtre de confidentialité. Certaines arêtes peuvent aussi comporter une limite maximale pour la valeur limit pour des raisons de performance. Dans tous les cas, l’API renvoie les liens de pagination corrects.
• next : point de terminaison de l’API Graph qui renvoie la page de données suivante.
• previous : point de terminaison de l’API Graph qui renvoie la page de données précédente.

Pagination en fonction de repères

La pagination en fonction de repères peut être utilisée lorsque la chronologie n’est pas importante et que vous souhaitez simplement recevoir un nombre spécifique d’objets. N’utilisez cette fonction que si l’arête ne prend pas en charge la pagination en fonction de curseurs ou du temps.

Une arête paginée en fonction de repères prend en charge les paramètres suivants :

• offset : début de chaque page en fonction du nombre indiqué.
• limit : nombre maximum d’objets pouvant être renvoyés. Une requête peut renvoyer moins d’objets que la valeur limit en raison d’un filtrage. N’attendez pas que le nombre de résultats soit inférieur à la valeur limit, utilisez plutôt l’absence de next comme décrit ci-dessous, pour indiquer que votre requête a atteint la fin de la liste de données. Par exemple, si vous définissez une limit sur 10 et que vous obtenez 9 résultats, d’autres données peuvent être disponibles, mais un élément a été supprimé en raison d’un filtre de confidentialité. Certaines arêtes peuvent aussi comporter une limite maximale pour la valeur limit pour des raisons de performance. Dans tous les cas, l’API renvoie les liens de pagination corrects.
• next : point de terminaison de l’API Graph qui renvoie la page de données suivante. S’il n’est pas inclus, il s’agit de la dernière page de données. En raison du fonctionnement de la pagination par rapport à la visibilité et à la confidentialité, une page peut à la fois être vide et contenir un lien de pagination next. Cessez la pagination lorsque le lien next n’apparaît plus.
• previous : point de terminaison de l’API Graph qui renvoie la page de données précédente. S’il n’est pas inclus, il s’agit de la première page de données.

Notez que l’ajout de nouveaux objets à la liste d’éléments paginés modifiera le contenu de chaque page basée sur des repères.

Vous pouvez rencontrer des limites durant la pagination d’objets dotés d’un grand nombre d’éléments renvoyés, comme les commentaires, qui peuvent se compter en dizaines de milliers. L’API renverra une erreur lorsque votre application aura atteint la limite du curseur :

{
  "error": {
    "message": "(#100) The After Cursor specified exceeds the max limit supported by this endpoint",
    "type": "OAuthException",
    "code": 100
  }
}

Étapes suivantes

Maintenant que vous connaissez mieux l’API Graph, consultez notre guide de l’outil Explorateur de l’API Graph afin de découvrir le graphique sans écrire de code et l’article Utilisations courantes pour afficher les tâches les plus couramment exécutées et les SDK disponibles.