Saltar al contenido principal

​
Introducción

La paginación es una característica de los endpoints de X API v2 que devuelven más resultados de los que pueden incluirse en una única respuesta. Cuando eso sucede, los datos se devuelven en una serie de “páginas”. La paginación hace referencia a los métodos para solicitar programáticamente 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 usarse cuando los conjuntos de resultados son grandes.

​
Casos de uso de la paginación

Para recuperar todos los resultados de una solicitud: Usa la paginación para obtener todos los datos relevantes relacionados con una solicitud y sus parámetros. La paginación es necesaria cuando hay más resultados coincidentes que el max_results de una solicitud. Repetir solicitudes con tokens de paginación te permite recuperar todos los resultados. Una vez que recibas una respuesta sin un next_token, puedes asumir que ya se han recorrido todos los resultados. No utilices la paginación para hacer sondeos. Para obtener los resultados más recientes desde una solicitud anterior, consulta el sondeo con since_id. Para recorrer 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 anterior de resultados.

​
Definiciones de tokens de paginación

  • next_token - Cadena opaca devuelta dentro del objeto meta en 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 siguiente página de resultados. La última página de resultados no incluirá un next_token.
    • previous_token - Cadena opaca devuelta dentro del objeto meta en respuestas de endpoints que admiten paginación. Indica que hay una página anterior de resultados disponible y puede usarse como el parámetro pagination_token en la siguiente solicitud para obtener la página anterior de resultados.
    • pagination_token - Parámetro utilizado en solicitudes de paginación. Establézcalo con el valor de next_token para la siguiente página 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 responden a una solicitud inicial con la primera página de resultados y proporcionan un next_token dentro del objeto meta en la respuesta JSON si hay páginas adicionales disponibles. Para recibir todos los resultados, repite este proceso hasta que la respuesta ya no incluya un next_token.
    • Los resultados se entregan en orden cronológico inverso. Esto se cumple dentro de cada página y también entre páginas:
      • El primer Post de la primera respuesta será el más reciente.
      • El último Post de la última respuesta será el más antiguo.
    • El parámetro de solicitud max_results te permite configurar la cantidad de Posts devueltos por página de respuesta. Existe 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 usarse en solicitudes posteriores.
    • En algunas circunstancias, puedes obtener menos de max_results por página. No confíes en que los resultados por página siempre sean iguales al valor del parámetro max_results.
    • Las mejores formas de usar 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

Hay tres páginas de resultados porque max_results está configurado 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 la solicitudmax_results=100tweet.fields=created_atstart_time=2019-01-01T17:00:00Zend_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=7140wmax_results=100tweet.fields=created_atstart_time=2019-01-01T17:00:00Zend_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": "Gracias a todos los que se conectaron hoy..." }, ... , { "created_at": "2020-05-06T17:24:31.000Z", "id": "1258085245091368960", "text": "Ahora es más fácil entender el impacto de los Tweet..." } ], "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": "Nuestra comunidad de desarrolladores está llena de ideas inspiradoras..." }, ... , { "created_at": "2019-11-21T16:17:23.000Z", "id": "1197549579035496449", "text": "Pronto lanzaremos herramientas en..." } ], "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": "Sabemos que algunas personas que reciben un gran volumen de respuestas pueden..." }, ... , { "created_at": "2019-01-08T19:19:37.000Z", "id": "1082718487011885056", "text": "Actualizaciones de los insertos de Grid..." } ], "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 tomar para la próxima solicitudPara obtener la página siguiente, toma elnext_tokenvalor directamente desde la respuesta (7140w) y establécelo como elpagination_tokenpara la siguiente llamada de solicitud.Para seguir obteniendo todos los resultados: toma elnext_tokenvalor directamente de la respuesta (7140k9) y establécelo como elpagination_tokenpara la siguiente llamada de solicitud. Para ir a la página anterior: toma elprevious_tokenvalor directamente de la respuesta (77qp8) y configúralo comopagination_tokenpara la siguiente llamada de la solicitud.Para seguir obteniendo todos los resultados: toma elnext_tokenvalor directamente de la respuesta (71408hi) y establécelo comopagination_tokenpara la siguiente llamada de la solicitud. Para ir a la página anterior: toma elprevious_tokenvalor directamente de la respuesta (77qplte) y establécelo como elpagination_tokenpara la siguiente llamada de solicitud.Tenga en cuenta que no existenext_token, lo que indica que se han recibido todos los resultados. Para ir a la página anterior: tome elprevious_tokenvalor directamente de la respuesta (77qpw8l) y establécelo como elpagination_tokenpara la siguiente llamada de solicitud.