Saltar al contenido principal

​
Introducción

La paginación es una función de los endpoints de X API v2 que devuelven más resultados de los que se pueden incluir en una sola respuesta. Cuando esto ocurre, los datos se devuelven en una serie de “páginas”. La paginación se refiere a los métodos para solicitar de forma programática todas las páginas y recuperar el conjunto completo de resultados. No todos los endpoints de la API admiten o requieren paginación, pero suele utilizarse cuando los conjuntos de resultados son grandes.

​
Casos de uso de la paginación

Para obtener todos los resultados de una solicitud: Use la paginación para recibir todos los datos relevantes asociados a una solicitud específica y sus parámetros. La paginación es necesaria cuando hay más resultados coincidentes que el valor de max_results de una solicitud. Iterar solicitudes con tokens de paginación permite obtener todos los resultados. Una vez que se recibe una respuesta sin un next_token, se puede asumir que ya se han recorrido todas las páginas de resultados. No use la paginación para realizar sondeos. Para obtener los resultados más recientes desde una solicitud anterior, consulte el sondeo con since_id. Para desplazarse por los resultados de una solicitud: La paginación ofrece opciones direccionales para navegar por los resultados de una solicitud, utilizando los valores next_token y previous_token de las respuestas. Estos tokens se pueden establecer como pagination_token en la solicitud siguiente para ir a la página siguiente o a la anterior de resultados.

​
Definiciones de tokens de paginación

  • next_token - Cadena opaca devuelta en el objeto meta en las respuestas de endpoints que admiten paginación. Indica que hay más resultados disponibles y puede usarse como el parámetro pagination_token en la siguiente solicitud para obtener la página siguiente de resultados. La última página de resultados no incluirá un next_token.
    • previous_token - Cadena opaca devuelta en el objeto meta en las respuestas de endpoints que admiten paginación. Indica que hay una página anterior de resultados disponible y puede establecerse como el parámetro pagination_token en la siguiente solicitud para obtener la página anterior de resultados.
    • pagination_token - Parámetro usado en solicitudes de paginación. Establézcalo con el valor de next_token para la página siguiente de resultados. Establézcalo con el valor de previous_token para la página anterior de resultados.

​
Fundamentos de la paginación

  • Los endpoints que usan paginación responderán a una solicitud inicial con la primera página de resultados y proporcionarán un next_token dentro del objeto meta en la respuesta JSON si hay páginas adicionales disponibles. Para recibir todos los resultados, repita este proceso hasta que la respuesta ya no incluya un next_token.
    • Los resultados se entregan en orden cronológico inverso. Esto aplica tanto dentro de cada página como entre páginas sucesivas:
      • El primer Post en la primera respuesta será el más reciente.
      • El último Post en la última respuesta será el más antiguo.
    • El parámetro de solicitud max_results le permite configurar la cantidad de Posts devueltos por página de respuesta. Existen un valor predeterminado y un valor máximo para max_results.
    • Toda implementación de paginación implicará extraer tokens del payload de la respuesta, que pueden utilizarse en solicitudes posteriores.
    • En algunas circunstancias, puede obtener menos elementos que el valor de max_results por página. No suponga que los resultados por página siempre serán iguales al valor del parámetro max_results.
    • Las mejores maneras de utilizar la paginación para obtener resultados completos son mediante lógica de bucle en el código de integración o utilizando una biblioteca compatible con X API v2.

​
Ejemplo de paginación

Aquí hay tres páginas de resultados porque max_results está establecido en 100, y hay aproximadamente 295 Posts creados por el id de usuario 2244994945 (@XDevelopers) entre el 1 de enero de 2019 a las 17:00:00 UTC y el 12 de diciembre a las 00:00:00 UTC. El primer Post de la primera página (1337498609819021312) es el más reciente, y el último Post de la tercera página de resultados (1082718487011885056) es el más antiguo.

​
Solicitud inicial

      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

​
Tabla de secuencia

Primera SolicitudSegunda PáginaTercera PáginaCuarta Página
Parámetros de Solicitud- 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
Respuestajson { "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" } }
Acciones a Realizar para la Siguiente SolicitudPara obtener la siguiente página, tome el valor de next_token directamente de la respuesta (7140w) y establézcalo como el pagination_token para la siguiente llamada de solicitud.Para continuar obteniendo todos los resultados: tome el valor de next_token directamente de la respuesta (7140k9) y establézcalo como el pagination_token para la siguiente llamada de solicitud. Para navegar a la página anterior: tome el valor de previous_token directamente de la respuesta (77qp8) y establézcalo como el pagination_token para la siguiente llamada de solicitud.Para continuar obteniendo todos los resultados: tome el valor de next_token directamente de la respuesta (71408hi) y establézcalo como el pagination_token para la siguiente llamada de solicitud. Para navegar a la página anterior: tome el valor de previous_token directamente de la respuesta (77qplte) y establézcalo como el pagination_token para la siguiente llamada de solicitud.Tenga en cuenta que no hay next_token, lo que indica que se han recibido todos los resultados. Para navegar a la página anterior: tome el valor de previous_token directamente de la respuesta (77qpw8l) y establézcalo como el pagination_token para la siguiente llamada de solicitud.
⌘I