Seitenumbruch

​

Einführung

Paginierung ist eine Funktion in X API v2-endpoints, die mehr Ergebnisse liefern, als in einer einzelnen Antwort zurückgegeben werden können. In diesem Fall werden die data in einer Reihe von „Seiten“ zurückgegeben. Paginierung bezeichnet Methoden, mit denen programmgesteuert alle Seiten angefordert werden, um den vollständigen Ergebnissatz abzurufen. Nicht alle API endpoints unterstützen oder erfordern Paginierung, sie wird jedoch häufig verwendet, wenn die Ergebnismengen groß sind.

​

Anwendungsfälle für die Paginierung

Um alle Ergebnisse für eine Anfrage abzurufen: Paginierung sollte verwendet werden, um alle relevanten data zu einer bestimmten Anfrage und deren Parametern zu erhalten. Paginierung ist erforderlich, wenn es mehr passende Ergebnisse gibt als durch max_results pro Anfrage zulässig. Das Wiederholen von Anfragen mit Paginierungs-Tokens ermöglicht es, alle Ergebnisse abzurufen. Sobald eine Antwort ohne next_token zurückgegeben wird, kann davon ausgegangen werden, dass alle Ergebnisse durchlaufen wurden. Paginierung sollte nicht für Polling-Zwecke verwendet werden. Um die aktuellsten Ergebnisse seit einer vorherigen Anfrage zu erhalten, verwenden Sie Polling mit since_id.

Um durch die Ergebnisse einer Anfrage zu blättern: Paginierung bietet gerichtete Optionen zum Navigieren durch die Ergebnisse einer Anfrage mithilfe der next_token- und previous_token-Werte aus den Antworten. Diese Tokens können im Anschluss als pagination_token in der nächsten Anfrage gesetzt werden, um zur nächsten oder vorherigen Ergebnisseite zu wechseln.

​

Definitionen von Pagination-Tokens

• next_token - Opaque Zeichenfolge, die innerhalb des meta-Objekts in Antworten von endpoints zurückgegeben wird, die Paginierung unterstützen. Weist darauf hin, dass weitere Ergebnisse verfügbar sind, und kann als Parameter pagination_token in der nächsten Anfrage verwendet werden, um die nächste Ergebnisseite abzurufen. Die letzte Ergebnisseite enthält kein next_token.
  • previous_token - Opaque Zeichenfolge, die innerhalb des meta-Objekts in Antworten von endpoints zurückgegeben wird, die Paginierung unterstützen. Weist darauf hin, dass eine vorherige Ergebnisseite verfügbar ist, und kann als Parameter pagination_token in der nächsten Anfrage gesetzt werden, um die vorherige Ergebnisseite abzurufen.
  • pagination_token - Parameter, der in Paginierungsanfragen verwendet wird. Für die nächste Ergebnisseite auf den Wert von next_token setzen. Für die vorherige Ergebnisseite auf den Wert von previous_token setzen.

​

Grundlagen der Paginierung

• Endpoints, die Paginierung verwenden, antworten auf eine erste Anfrage mit der ersten Ergebnisseite und liefern ein next_token im meta-Objekt der JSON-Antwort, wenn weitere Ergebnisseiten verfügbar sind. Um alle Ergebnisse zu erhalten, wiederholen Sie diesen Vorgang, bis kein next_token mehr in der Antwort enthalten ist.
  • Ergebnisse werden in umgekehrt chronologischer Reihenfolge geliefert. Dies gilt sowohl innerhalb einzelner Seiten als auch über mehrere Seiten hinweg:
    • Der erste Post in der ersten Antwort ist der jüngste.
    • Der letzte Post in der letzten Antwort ist der älteste.
  • Der Anfrageparameter max_results ermöglicht es Ihnen, die Anzahl der pro Antwortseite zurückgegebenen Posts zu konfigurieren. Es gibt einen Standard- und einen Höchstwert für max_results.
  • Jede Paginierungsimplementierung umfasst das Parsen von Tokens aus der Antwortnutzlast, die in nachfolgenden Anfragen verwendet werden können.
  • Unter bestimmten Umständen erhalten Sie möglicherweise weniger Ergebnisse pro Seite als in max_results angegeben. Verlassen Sie sich nicht darauf, dass die Anzahl der Ergebnisse pro Seite immer dem Parameterwert max_results entspricht.
  • Die besten Vorgehensweisen für vollständige Ergebnisse sind die Verwendung von Schleifenlogik im Integrationscode oder die Nutzung einer Bibliothek, die X API v2 unterstützt.

​

Paginierungsbeispiel

Hier gibt es drei Ergebnisseiten, weil max_results auf 100 gesetzt ist und ungefähr 295 Posts vom Benutzer mit der id 2244994945 (@XDevelopers) zwischen dem 1. Januar 2019 um 17:00:00 UTC und dem 12. Dezember um 00:00:00 UTC erstellt wurden. Der erste Post auf der ersten Seite (1337498609819021312) ist der neueste, und der letzte Post auf der dritten Ergebnisseite (1082718487011885056) ist der älteste.

​

Erstanforderung

      https://api.x.com/2/users/2244994945/tweets?tweet.fields=created_at&max_results=100&start_time=2019-01-01T17:00:00Z&end_time=2020-12-12T01:00:00Z

​

Sequenz­tabelle

	Erste Anfrage	Zweite Seite	Dritte Seite	Vierte Seite
Request Parameters	- max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z	- max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z - pagination_token = 7140w	- max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z - pagination_token = 7140k9	- max_results = 100 - tweet.fields = created_at - start_time = 2019-01-01T17:00:00Z - end_time = 2020-12-12T01:00:00Z - pagination_token = 71408hi
Response	json { "data": [ { "created_at": "2020-12-11T20:44:52.000Z", "id": "1337498609819021312", "text": "Thanks to everyone who tuned in today..." }, ... , { "created_at": "2020-05-06T17:24:31.000Z", "id": "1258085245091368960", "text": "It’s now easier to understand Tweet impact..." } ], "meta": { "oldest_id": "1258085245091368960", "newest_id": "1337498609819021312", "result_count": 100, "next_token": "7140w" } }	json { "data": [ { "created_at": "2020-04-29T17:01:44.000Z", "id": "1255542797765013504", "text": "Our developer community is full of inspiring ideas..." }, ... , { "created_at": "2019-11-21T16:17:23.000Z", "id": "1197549579035496449", "text": "Soon, we'll be releasing tools in..." } ], "meta": { "oldest_id": "1197549579035496449", "newest_id": "1255542797765013504", "result_count": 100, "next_token": "7140k9", "previous_token": "77qp8" } }	json { "data": [ { "created_at": "2019-11-21T16:17:23.000Z", "id": "1197549578418941952", "text": "We know that some people who receive a large volume of replies may..." }, ... , { "created_at": "2019-01-08T19:19:37.000Z", "id": "1082718487011885056", "text": "Updates to Grid embeds..." } ], "meta": { "oldest_id": "1082718487011885056", "newest_id": "1197549578418941952", "result_count": 95, "next_token": "71408hi", "previous_token": "77qplte" } }	json { "meta": { "result_count": 0, "previous_token": "77qpw8l" } }
Actions to Take for Next Request	Um die nächste Seite abzurufen, übernehmen Sie den Wert von next_token direkt aus der Antwort (7140w) und setzen Sie ihn als pagination_token für den nächsten Request.	Um weiterhin alle Ergebnisse abzurufen: Übernehmen Sie den Wert von next_token direkt aus der Antwort (7140k9) und setzen Sie ihn als pagination_token für den nächsten Request. Um zur vorherigen Seite zu wechseln: Übernehmen Sie den Wert von previous_token direkt aus der Antwort (77qp8) und setzen Sie ihn als pagination_token für den nächsten Request.	Um weiterhin alle Ergebnisse abzurufen: Übernehmen Sie den Wert von next_token direkt aus der Antwort (71408hi) und setzen Sie ihn als pagination_token für den nächsten Request. Um zur vorherigen Seite zu wechseln: Übernehmen Sie den Wert von previous_token direkt aus der Antwort (77qplte) und setzen Sie ihn als pagination_token für den nächsten Request.	Beachten Sie, dass kein next_token vorhanden ist. Das bedeutet, dass alle Ergebnisse abgerufen wurden. Um zur vorherigen Seite zu wechseln: Übernehmen Sie den Wert von previous_token direkt aus der Antwort (77qpw8l) und setzen Sie ihn als pagination_token für den nächsten Request.