Graph API

Paginierte Ergebnisse

Wir behandeln die Grundlagen der Graph API-Terminologie und -Struktur in der Graph API-Übersicht. In diesem Dokument beschäftigen wir uns näher mit den Ergebnissen aus deinen API-Anfragen.

Durchlaufen paginierter Ergebnisse

Wenn du eine API-Anfrage für einen Node oder eine Edge ausführst, erhältst du normalerweise nicht alle Ergebnisse dieser Anfrage in einer einzelnen Antwort. Dies liegt daran, dass einige Antworten Tausende Objekte beinhalten könnten. Daher sind die meisten Antworten standardmäßig paginiert.

Cursor-basierte Paginierung

Die cursor-basierte Paginierung stellt die effizienteste Paginierungsmethode dar und sollte nach Möglichkeit immer verwendet werden. Ein Cursor bezieht sich auf einen zufälligen String für ein bestimmtes Element in einer Datenliste. Der Cursor zeigt immer auf das Element. Er wird jedoch ungültig, wenn ein Element gelöscht oder entfernt wird. Daher sollte deine App keine Cursor speichern oder davon ausgehen, dass diese in Zukunft gültig sind.

Beim Lesen einer Edge, die Cursor-Paginierung unterstützt, siehst du die folgende JSON-Antwort:

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

Eine cursor-paginierte Edge unterstützt die folgenden Parameter:

  • before: Dies ist der Cursor, der auf den Anfang der Seite mit den zurückgegebenen Daten verweist.
  • after: Dies ist der Cursor, der auf das Ende der Seite mit den zurückgegebenen Daten verweist.
  • limit: Dies ist die maximale Anzahl an Objekten, die zurückgegeben werden kann. Aufgrund der Filterung wird bei einer Abfrage möglicherweise ein geringerer Wert als limit zurückgegeben. Wenn die Zahl der Ergebnisse geringer ist als der limit-Wert, ist das kein hinreichender Beweis dafür, dass für deine Abfrage das Ende der Datenliste erreicht wurde. Orientiere dich stattdessen an der Abwesenheit des Parameters next (siehe unten). Wenn du beispielsweise limit auf den Wert „10“ festlegst und 9 Ergebnisse zurückgegeben werden, sind möglicherweise weitere Daten verfügbar, es wurde jedoch ein Element aufgrund des Privatsphäre-Filters entfernt. Einige Edges weisen möglicherweise aus Gründen der Performance einen Höchstwert für den Wert limit auf. In jedem Fall gibt die API die richtigen Paginierungslinks zurück.
  • next: Der Graph API-Endpunkt, der die nächste Datenseite zurückgibt. Wenn nicht vorhanden, handelt es sich hierbei um die letzte Datenseite. Aufgrund des Zusammenhangs zwischen Paginierung und Sichtbarkeit/Datenschutz kann es vorkommen, dass eine Seite leer ist, aber den Paginierungslink next enthält. Du solltest die Paginierung beenden, wenn der Link next nicht mehr auftaucht.
  • previous: Der Graph API-Endpunkt, der die vorherige Datenseite zurückgibt. Wenn nicht vorhanden, handelt es sich hierbei um die erste Datenseite.

Speichere keine Cursor. Durch das Hinzufügen oder Entfernen von Elementen können Cursor schnell ungültig werden.

Zeitbasierte Paginierung

Anhand der Zeitpaginierung kannst du mit UNIX-Zeitstempeln, die auf bestimmte Zeiten in einer Datenliste verweisen, durch Ergebnisdaten navigieren.

Beim Verwenden eines Endpunkts, der die zeitbasierte Paginierung verwendet, siehst du die folgende JSON-Antwort:

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

Eine zeitpaginierte Edge unterstützt die folgenden Parameter:

  • until: Ein Unix-Zeitstempel oder strtotime-Datenwert, der auf das Ende des Bereichs mit den zeitbasierten Daten verweist.
  • since: Ein Unix-Zeitstempel oder strtotime-Datenwert, der auf den Anfang des Bereichs mit den zeitbasierten Daten verweist.
  • limit : Dies ist die maximale Anzahl an Objekten, die zurückgegeben werden kann. Aufgrund der Filterung wird bei einer Abfrage möglicherweise ein geringerer Wert als limit zurückgegeben. Die Anzahl der Ergebnisse darf nicht zwingend geringer sein als der limit-Wert, um anzugeben, dass für deine Abfrage das Ende der Datenliste erreicht wurde. Verwende in diesem Fall stattdessen eine Abfrage ohne den nachfolgend erläuterten Parameter next. Wenn du beispielsweise limit auf den Wert „10“ festlegst und 9 Ergebnisse zurückgegeben werden, sind möglicherweise weitere Daten verfügbar, es wurde jedoch ein Element aufgrund des Privatsphäre-Filters entfernt. Einige Edges weisen möglicherweise aus Gründen der Performance einen Höchstwert für den Wert limit auf. In jedem Fall gibt die API die richtigen Paginierungslinks zurück.
  • next: Der Graph API-Endpunkt, der die nächste Datenseite zurückgibt.
  • previous: Der Graph API-Endpunkt, der die vorherige Datenseite zurückgibt.

Gib sowohl den Parameter since als auch den Parameter until an, um konsistente Ergebnisse zu erhalten. Außerdem empfehlen wir, einen Zeitabstand von höchstens 6 Monaten zu verwenden.

Offset-basierte Paginierung

Du kannst die Offset-Paginierung verwenden, wenn die chronologische Anordnung keine Rolle spielt und du einfach eine bestimmte Anzahl an Objekten zurückgeben möchtest. Dies solltest du nur verwenden, wenn die Edge keine Cursor- oder zeitbasierte Paginierung unterstützt.

Eine Offset-paginierte Edge unterstützt die folgenden Parameter:

  • offset: Damit wird der Anfang jeder Seite um die angegebene Zahl versetzt.
  • limit: Dies ist die maximale Anzahl an Objekten, die zurückgegeben werden kann. Aufgrund der Filterung wird bei einer Abfrage möglicherweise ein geringerer Wert als limit zurückgegeben. Wenn die Zahl der Ergebnisse geringer ist als der limit-Wert, ist das kein hinreichender Beweis dafür, dass für deine Abfrage das Ende der Datenliste erreicht wurde. Orientiere dich stattdessen an der Abwesenheit des Parameters next (siehe unten). Wenn du beispielsweise limit auf den Wert „10“ festlegst und 9 Ergebnisse zurückgegeben werden, sind möglicherweise weitere Daten verfügbar, es wurde jedoch ein Element aufgrund des Privatsphäre-Filters entfernt. Einige Edges weisen möglicherweise aus Gründen der Performance einen Höchstwert für den Wert limit auf. In jedem Fall gibt die API die richtigen Paginierungslinks zurück.
  • next: Der Graph API-Endpunkt, der die nächste Datenseite zurückgibt. Wenn nicht vorhanden, handelt es sich hierbei um die letzte Datenseite. Aufgrund des Zusammenhangs zwischen Paginierung und Sichtbarkeit/Datenschutz kann es vorkommen, dass eine Seite leer ist, aber den Paginierungslink next enthält. Du solltest die Paginierung beenden, wenn der Link next nicht mehr auftaucht.
  • previous: Der Graph API-Endpunkt, der die vorherige Datenseite zurückgibt. Wenn nicht vorhanden, handelt es sich hierbei um die erste Datenseite.

Hinweis: Wenn neue Objekte der Liste mit den zu durchblätternden Elementen hinzugefügt werden, ändert sich der Inhalt jeder offset-basierten Seite.

Die offset-basierte Paginierung wird nicht bei allen API-Aufrufen unterstützt. Um konsistente Ergebnisse zu erreichen, solltest du über die in der Antwort zurückgegebenen Links „previous/next“ paginieren.

Bei Objekten, die über viele zurückgegebene Elemente verfügen, wie zum Beispiel comments, deren Anzahl in die Zehntausenden gehen kann, stößt du beim Paginieren eventuell auf Grenzen. Die API zeigt einen Fehler an, wenn deine App das Cursorlimit erreicht hat:

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

Nächste Schritte

Jetzt, wo du mit der Graph API vertrauter bist, kannst du in unserem Leitfaden für das Graph Explorer-Tool den Graph ohne Programmierkenntnisse genauer erkunden, unter Häufige Anwendungsfälle die am häufigsten durchgeführten Aufgaben anzeigen und prüfen, welche SDKs zur Verfügung stehen.