Verwenden der Graph API

Wir behandeln die Grundlagen der Graph API-Terminologie und -Struktur in der Graph API-Übersicht. In diesem Dokument werden die verschiedenen Vorgänge näher erläutert, die du mit der Graph API ausführen kannst.

HTTP/1.1

Alle Datenübertragungen entsprechen HTTP/1.1; für alle Endpunkte ist HTTPS erforderlich. Wir haben außerdem die includeSubdomains HSTS-Direktive auf facebook.com aktiviert. Hierdurch sollten Graph API-Anfragen nicht beeinträchtigt werden.

Host-URL

Fast alle Anfragen werden an die Host-URL graph.facebook.com übergeben. Die einzige Ausnahme sind Video-Uploads, die graph-video.facebook.com verwenden.

Zugriffsschlüssel

Deine App kann über Zugriffsschlüssel auf die Graph API zugreifen. Zugriffsschlüssel führen in der Regel zwei Funktionen aus:

  • Deine App kann auf die Informationen eines Nutzers zugreifen, ohne dass das Passwort des Nutzers erforderlich ist
  • Sie ermöglichen es, deine App, den Benutzer, der deine App verwendet, und die Art der Daten zu identifizieren, auf die der Nutzer deiner App Zugriff gewährt.

Alle Graph API-Endpunkte erfordern einen bestimmten Zugriffsschlüssel. Daher muss deine Anfrage bei jedem Zugriff auf einen Endpunkt einen Zugriffsschlüssel enthalten.

Funktionsweise von Zugriffsschlüsseln

Zugriffsschlüssel entsprechen dem OAuth 2.0-Protokoll. OAuth 2.0 erlaubt Entitäten, z. B. einem Nutzer oder einer Seite, die Autorisierung von Schlüsseln. Dies erfolgt normalerweise über eine Weboberfläche. Nach erfolgter Autorisierung können Apps diese Schlüssel nutzen, um auf bestimmte Informationen zuzugreifen.

Im vorliegenden Beispiel fragt die App den Nutzer nach der Erteilung der Berechtigung für den Zugriff auf Fotos, Videos und die E-Mail-Adresse des Nutzers:

Wie du siehst, handelt es sich um eine Facebook-Benutzeroberfläche. Der Nutzer hat sich gerade über die Benutzeroberfläche bei seinem Konto angemeldet, wodurch wir den Nutzer authentifizieren konnten. Im weiteren Verlauf wird der alte Zugriffsschlüssel (App-Schlüssel) durch einen neuen (Nutzer-Schlüssel) ersetzt. Die App kann diesen neuen Nutzer-Schlüssel nun verwenden, um Graph API-Anfragen zu senden. Es ist in diesem Fall nur der Zugriff auf Fotos, Videos und die E-Mail-Adresse dieses spezifischen Nutzers möglich.

Das ist ein wichtiges Attribut von Zugriffsschlüsseln. Die App- und Nutzer-IDs werden (neben anderen Elementen) im Schlüssel selbst verschlüsselt. Wir verwenden diese IDs, um nachzuverfolgen, für welche Daten der Nutzer den Zugriff durch die App genehmigt hat. Wenn du den Schlüssel beispielsweise nach der vom Nutzer gewährten Genehmigung untersuchst, werden folgende Informationen bereitgestellt:

Schlüssel gewähren nicht nur Zugriff auf die Daten des Nutzers, sondern können von allen genutzt werden und sind extrem wertvoll. Aus diesem Grund solltest du entsprechende Vorsichtsmaßnahmen treffen, wenn du sie in deinen Abfragen nutzt. Die einfachste Möglichkeit, dies zu erreichen, ist, Facebook Login zur Verarbeitung deiner Schlüssel zu verwenden.

Facebook Login

OAuth 2.0 umfasst zahlreiche Weiterleitungen, Anmeldeaufforderungen und Zugriffsschlüsselaustauschvorgänge. Um dir die Arbeit zu erleichtern, haben wir Facebook Login entwickelt. Facebook Login zeichnet sich durch einfach zu verwendende Funktionen und Methoden für alle unsere SDKs aus. So ist das Verwenden von Zugriffsschlüsseln viel einfacher als das Erstellen einer eigenen Lösung.

In der Dokumentation zu Facebook Login kannst du mehr über Zugriffsschlüssel und Facebook Login erfahren. Dort findest du auch Informationen zum Erstellen einer eigenen Lösung.

Lesen

Nodes

Lesevorgänge beginnen meist bei einem Node. Ein Node ist ein einzelnes Objekt mit einer eindeutigen ID. Es gibt beispielsweise viele Seiten-Node-Objekte, wobei jedes eine eindeutige ID aufweist. Die Seite von Coca-Cola ist die einzige mit der ID 820882001277849. Um einen Lesevorgang für einen bestimmten Node auszuführen, fragst du die ID eines spezifischen Objekts ab. Um einen Lesevorgang für die Coca-Cola-Seite auszuführen, würdest du die entsprechende ID abfragen:

GET https://graph.facebook.com/v2.11
  /820882001277849

Bei der Abfrage werden standardmäßig die folgenden Felder (Node-Eigenschaften) zurückgegeben, die in JSON formatiert sind:

{
  "name": "Coca-Cola",
  "id": "820882001277849"
}

Edges

Nodes verfügen in der Regel über Edges, die Sammlungen von anderen Nodes zurückgeben, die damit verknüpft sind. Um einen Lesevorgang für eine Edge auszuführen, musst du sowohl die Node-ID als auch den Namen der Edge im Pfad verwenden. Die /page-Nodes verfügen beispielsweise über eine /feed-Edge, die alle Post-Nodes für eine Seite zurückgeben kann. Du kannst die Edge beispielsweise wie folgt verwenden, um alle Posts auf der Coca-Cola-Seite abzurufen:

GET https://graph.facebook.com/v2.11
  /820882001277849
    /feed

Die JSON-Antwort sieht in etwa wie folgt aus:

{
  "data": [
    {
      "created_time": "2017-12-08T01:08:57+0000",
      "message": "Love this puzzle. One of my four coke puzzles",
      "id": "820882001277849_1805191182846921"
    },
    {
      "created_time": "2017-12-07T20:06:14+0000",
      "message": "You need to add grape as a flavor for Coke in your freestyle machines.",
      "id": "820882001277849_1804966026202770"
    },
    {
      "created_time": "2017-12-07T01:29:12+0000",
      "message": "Plz play the old commercial’s with the polar bears. Would be nice to see them this holiday",
      "id": "820882001277849_1804168469615859"
    }
  ]
}

Beachte, dass die Antwort nicht nur die IDs der Post-Nodes in der Sammlung enthält, sondern auch die Felder created_time und message. Das ist üblich. Die meisten Edges binden standardmäßig eines oder mehrere Felder ein.

Felder

Felder sind Node-Eigenschaften. Wenn du eine Abfrage an einen Node sendest, gibt dieser standardmäßig verschiedene Felder zurück – wie im Beispiel oben gezeigt. Du kannst jedoch angeben, welche Felder zurückgegeben werden sollen, indem du für jedes Feld den fields-Parameter und Listen verwendest. Damit wird die Standardeinstellung überschrieben und es werden nur die von dir definierten Felder zurückgegeben. Darüber hinaus wird die ID des Objekts zurückgegeben (diese wird immer zurückgegeben).

In der Referenz zum Node für die Seite ist beispielsweise angegeben, welche Felder du beim Lesen eines Seiten-Node abfragen kannst. Wenn du die Felder about, fan_count und website für die Coca-Cola-Seite abfragen möchtest, kannst du dies wie folgt tun:

GET https://graph.facebook.com/v2.11
  /820882001277849
    ?fields=about,fan_count,website

Damit wird die folgende Antwort zurückgegeben:

{
  "about": "Welcome to the happiest Facebook page on, um, Facebook.",
  "fan_count": 106714402,
  "website": "http://coca-cola.com",
  "id": "820882001277849"
}

Edges, die normalerweise Sammlungen von Objekten zurückgeben, geben auch Felder zu den einzelnen Objekten in der Sammlung zurück. Angenommen, du hast mit der /photos-Edge alle Foto-Nodes auf der Coca-Cola-Seite abgerufen:

GET https://graph.facebook.com/v2.11
  /820882001277849
    /photos

Damit wird eine Antwort ähnlich der folgenden erzeugt:

{
  "data": [
    {
      "created_time": "2016-08-23T13:12:10+0000",
      "id": "1308573619175349"
    },
    {
      "created_time": "2016-08-05T22:34:19+0000",
      "id": "1294456907253687"
    },
    {
      "created_time": "2016-04-29T16:17:02+0000",
      "id": "1228552183844160"
    }
  ]
}

Wie du sehen kannst, gibt die /photos-Edge standardmäßig eine Sammlung der Foto-Node-IDs sowie die Eigenschaft created_time für alle Fotos zurück. Ebenso wie bei den Nodes kannst du den fields-Parameter nutzen, um anzugeben, welche Felder für die einzelnen Objekte, die in der Sammlung zurückgegeben werden, zurückgegeben werden sollen.

Angenommen, du möchtest die Felder height, width und link (URL) für die einzelnen Foto-Nodes abrufen, die von der /photos-Edge zurückgegeben wurden:

GET https://graph.facebook.com/v2.11
  /820882001277849
    /photos
      ?fields=height,width,link

Die Antwort sieht wie folgt aus:

{
  "data": [
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1308573619175349/?type=3",
      "id": "1308573619175349"
    },
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1294456907253687/?type=3",
      "id": "1294456907253687"
    },
    {
      "height": 180,
      "width": 180,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1228552183844160/?type=3",
      "id": "1228552183844160"
    }
  ]
}

Beachte Folgendes: Du kannst auch eine Edge mit dem fields-Parameter angeben. Das ist hilfreich, wenn du die Felderweiterung nutzt.

Felderweiterung

Wenn du zuvor bereits die Abfrage GET /page/photos im Graphi API Explorer getestet hast, konntest du sicher feststellen, dass mit der Abfrage mehr als drei Objekte zurückgegeben wurden und die Ergebnisse paginiert sind. Das ist bei den meisten Edges üblich. Das Thema Durchlaufen paginierter Ergebnisse folgt weiter unten. Zunächst beschäftigen wir uns mit der Felderweiterung. Diese ermöglicht es dir nicht nur, verschachtelte Anfragen zu senden, sondern die Ergebnisse auch zu beschränken und zu ordnen.

Ergebnisse einschränken

Durch die Einschränkung kannst du die Anzahl der Objekte definieren, die in den einzelnen paginierten Ergebnissätzen zurückgegeben werden. Du schränkst die Ergebnisse ein, indem du an ein beliebiges Feld oder eine beliebige Edge ein .limit()-Argument anfügst.

Wenn du beispielsweise eine GET-Anfrage für die /feed-Edge der Coca-Cola-Seite ausführst, werden möglicherweise Hunderte Posts zurückgegeben. Du kannst die Anzahl der Posts, die pro Ergebnisseite zurückgegeben werden, wie folgt beschränken:

GET https://graph.facebook.com/v2.11
  /820882001277849
    ?fields=feed.limit(3)

Damit werden alle Posts auf der Coca-Cola-Seite zurückgegeben, die Anzahl der Objekte auf den einzelnen Seiten ist jedoch auf 3 beschränkt. Beachte dabei Folgendes: Statt die Feed-Edge in der Pfad-URL (/page/feed) anzugeben, gibst du den fields-Parameter an (?fields=feed), damit du das .limit(3)-Argument anfügen kannst.

Damit ergeben sich die folgenden Abfrageergebnisse:

{
  "feed": {
    "data": [
      {
        "created_time": "2017-12-12T01:24:21+0000",
        "message": "This picture of my grandson with Santa screams Coca Cola",
        "id": "820882001277849_1809387339093972"
      },
      {
        "created_time": "2017-12-11T23:40:17+0000",
        "message": ":)",
        "id": "820882001277849_1809316002434439"
      },
      {
        "created_time": "2017-12-11T23:31:38+0000",
        "message": "Thought you might enjoy this.  My horse loves Coke!",
        "id": "820882001277849_1809310929101613"
      }
    ],
    "paging": {
      "cursors": {
        "before": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5UTRNakE0T0RJd01ERXlOemM0TkRrNkxUVXdPRE16TXpVM01EQXpNVFUwTkRRME5Ua1BER0ZA3YVY5emRHOXllVjlwWkE4ZA09ESXdPRGd5TURBeE1qYzNPRFE1WHpFNE1Ea3pPRGN6TXprd09UTTVOeklQQkhScGJXVUdXaTh2eFFFPQZDZD",
        "after": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5TTRNakE0T0RJd01ERXlOemM0TkRrNk1UTTJORE01T0RVNU1UZAzVPRGMyTnpFNE1BOE1ZAWEJwWDNOMGIzSjVYMmxrRHlBNE1qQTRPREl3TURFeU56YzRORGxmTVRnd09USXdOamsxTlRjM09EWTNOdzhFZAEdsdFpRWmFMdk9HQVE9PQZDZD"
      },
      "next": "https://graph.intern.facebook.com/v2.11/820882001277849/feed?access_token=valid_token_goes_here"
    }
  },
  "id": "820882001277849"
}

Wie du siehst, werden nur drei Objekte auf dieser Seite der paginierten Ergebnisse angezeigt. Die Antwort enthält ein next-Feld und eine URL, über die du die nächste Seite abrufen kannst.

Ergebnisse sortieren

Du kannst die Ergebnisse nach der Objekterstellungszeit sortieren. Dazu verwendest du für das Feld oder die Edge das .order()-Argument mit einem der folgenden Werte.

  • chronological: Die Ergebnisse werden so sortiert, dass das älteste erstellte Objekt an erster Stelle angezeigt wird.
  • reverse_chronological: Die Ergebnisse werden so sortiert, dass das neueste erstellte Objekt an erster Stelle angezeigt wird.

Angenommen, wir möchten alle Kommentare zu einem bestimmten Video-Post auf der Coca-Cola-Seite (1809938745705498) abrufen, die Ergebnisse in chronologischer Reihenfolge (also das älteste Element zuerst) anordnen und die Anzahl der Objekte pro paginierter Ergebnisseite auf drei begrenzen:

GET https://graph.facebook.com/v2.11
  /1809938745705498
    ?fields=comments.order(chronological).limit(3)

Auch hier musst du wieder darauf achten, dass du die Edge im fields-Parameter angibst, damit du ein Argument für die Edge verwenden kannst. Wie du siehst, kannst du die Argumente .limit() und .order() in einem einzelnen Feld oder einer einzelnen Edge kombinieren.

Die Ergebnisse sehen wie folgt aus:

{
  "comments": {
    "data": [
      {
        "created_time": "2017-12-12T14:12:20+0000",
        "message": ":) :) :)",
        "id": "1809938745705498_1809939942372045"
      },
      {
        "created_time": "2017-12-12T14:14:03+0000",
        "message": "seasons greetings!",
        "id": "1809938745705498_1809941802371859"
      },
      {
        "created_time": "2017-12-12T14:14:11+0000",
        "message": "My bestie <3",
        "id": "1809938745705498_1809941879038518"
      }
    ],
    "paging": {
      "cursors": {
        "before": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd3T1Rrek9UZAzROVGN3TlRNNE5Eb3hOVEV6TURnM09UTTIZD",
        "after": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd4TURBd09UazROVFk1T0RNM05Eb3hOVEV6TURreU5qQXoZD"
      },
      "next": "https://graph.intern.facebook.com/v2.11/1809938745705498/comments?access_token=valid_token_goes_here"
    }
  },
  "id": "1809938745705498"
}

Veröffentlichung

Für die meisten Edges können Objekte in einer Sammlung auf einem Node veröffentlicht werden. Du sendest dazu einfach eine POST-Anfrage an die Edge des entsprechenden Nodes. Du verwendest beispielsweise die /comments-Edge des Foto-Nodes, um einen Kommentar zu einem Foto zu veröffentlichen:

POST https://graph.facebook.com
  /1809938745705498
    /comments
      ?message=Awesome!

Bei einer erfolgreichen Abfrage geben die meisten Edges die ID des gerade veröffentlichten Objekts zurück. Dabei handelt es sich meist um eine Kombination aus der ID, mit der das Objekt veröffentlicht wurde, und einem neuen ID-String:

{
  "id": "1809938745705498_1810399758992730"
}

Für die Veröffentlichung sind normalerweise zusätzliche Berechtigungen erforderlich. In der Referenzdokumentation zu den einzelnen Edges kannst du nachlesen, welche Berechtigungen jeweils erforderlich sind.

Der Zugriffsschlüssel, der für die Veröffentlichung des Objekts verwendet wird, beeinflusst möglicherweise das Aussehen des Objekts. Wenn ein Seiten-Zugriffsschlüssel verwendet wird, sieht es so aus, als ob die Seite das Objekt gepostet hätte. Wenn du hingegen einen Nutzer-Zugriffsschlüssel verwendest, sieht es so aus, als ob das Objekt von einer Person gepostet worden wäre.

Viele Edges unterstützen auch erweiterte Funktionen wie Read-After-Write (Lesen nach Schreiben), wodurch du ein neu veröffentlichtes Objekt direkt lesen kannst, und Batch-Veröffentlichung, wobei du mehrere Veröffentlichungsvorgänge verketten kannst.

Aktualisieren

Du kannst mithilfe von POST-Anfragen Update-Vorgänge an einem bestehenden Node ausführen. Du kannst beispielsweise Folgendes ausführen, um das Feld message für einen bestehenden Kommentar zu aktualisieren:

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?message=Happy%20Holidays!

Bei erfolgreicher Ausführung gibt der Node ein success-Feld und den Wert true zurück:

{
  "success": true
}

Ähnlich wie bei Veröffentlichungsvorgängen sind für Update-Vorgänge bestimmte Berechtigungen erforderlich. Diese sind in der Referenzdokumentation der einzelnen Nodes angegeben. Wie die meisten Edges auch unterstützen viele Nodes Read-After-Write.

Löschen

Ein Node lässt sich normalerweise mit einem DELETE-Vorgang löschen:

DELETE https://graph.facebook.com
  /1809938745705498_1810399758992730

Bei erfolgreicher Ausführung gibt der Node ein success-Feld und den Wert true zurück:

{
  "success": true
}

In der Regel kannst du nur Nodes löschen, die du selbst erstellt hast. Eine ausführliche Erläuterung zu den Anforderungen für Löschvorgänge findest du in der Referenz der einzelnen Nodes.

Für Clients, die nicht alle HTTP-Methoden unterstützen, kannst du eine POST-Anfrage an den Node senden und den Parameter method=delete einbinden, um die HTTP-Methode außer Kraft zu setzen:

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?method=delete

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. Solange dieses Element nicht gelöscht wird, zeigt der Cursor immer auf denselben Teil der Liste. Er wird aber ungültig, wenn ein Element 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/me/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/me/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. 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. 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/me/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/me/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. 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. 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.