Saltar al contenido principal

​
Paginación de la búsqueda reciente

​
Introducción

Las consultas de búsqueda suelen arrojar más Posts de los que pueden devolverse en una sola respuesta de API. Cuando esto ocurre, los datos se devuelven en una serie de “páginas”. La paginación se refiere a los métodos para solicitar todas las páginas a fin de recuperar el conjunto de datos completo. A continuación, se presentan detalles fundamentales sobre la paginación en búsquedas recientes:
  • Los endpoints de búsqueda reciente responderán a una consulta con al menos una página y proporcionarán un next_token en su respuesta JSON si hay páginas adicionales disponibles. Para recibir los Posts coincidentes, este proceso puede repetirse hasta que no se incluya ningún token en la respuesta.
  • El next_token no caduca. Varias solicitudes que usen el mismo valor de next_token recibirán los mismos resultados, independientemente de cuándo se realice la solicitud.
  • Los Posts se entregan en orden cronológico inverso, en la zona horaria UTC. Esto es válido dentro de páginas individuales, así como a través de múltiples páginas:
    • El primer Post de la primera respuesta será el más reciente que coincida con tu consulta.
    • El último Post de la última respuesta será el más antiguo que coincida con tu consulta.
  • El parámetro de solicitud max_results te permite configurar la cantidad de Posts devueltos por respuesta. De manera predeterminada, es de 10 Posts y el máximo es 100.
  • Toda implementación de paginación implicará extraer los next_tokens del payload de la respuesta e incluirlos en la solicitud de búsqueda de la “próxima página”. Consulta a continuación más detalles sobre cómo construir estas solicitudes de “próxima página”.
El endpoint de búsqueda reciente se diseñó para admitir dos patrones de uso fundamentales:
  • Obtener histórico - Solicitar Posts coincidentes de un período de tiempo de interés. Por lo general, se trata de solicitudes puntuales en apoyo de investigaciones históricas. Las solicitudes de búsqueda pueden basarse en los parámetros de solicitud start_time y end_time. El endpoint de búsqueda reciente responde con Posts entregados en orden cronológico inverso, comenzando por el Post coincidente más reciente.
  • Sondeo - Solicitar Posts coincidentes que se hayan publicado desde el último Post recibido. Estos casos de uso a menudo tienen un enfoque casi en tiempo real y se caracterizan por solicitudes frecuentes, “escuchando” nuevos Posts de interés. El endpoint de búsqueda reciente proporciona el parámetro de solicitud since_id para admitir el patrón de “sondeo”. Para ayudar a navegar por los id de Post, también está disponible el parámetro de solicitud until_id.
A continuación, hablaremos del modo histórico. Este es el modo predeterminado del endpoint de búsqueda reciente y ejemplifica los fundamentos de la paginación. Después, hablaremos de ejemplos de casos de uso de sondeo. Cuando el sondeo activa la paginación, hay un paso adicional para gestionar las solicitudes de búsqueda.  

​
Recuperación de datos históricos

Esta sección describe cómo recuperar Posts de un período de interés (actualmente limitado a los últimos siete días) utilizando los parámetros de solicitud start_time y end_time. Las solicitudes históricas suelen ser peticiones puntuales para respaldar la investigación y el análisis. Solicitar un período de datos es el modo predeterminado del endpoint de búsqueda reciente. Si una solicitud de búsqueda no especifica los parámetros start_time, end_time o since_id, end_time tendrá como valor predeterminado «ahora» (en realidad, 30 segundos antes del momento de la consulta) y start_time tendrá como valor predeterminado siete días antes. El endpoint responderá con la primera «página» de Posts en orden cronológico inverso, comenzando por el Post más reciente. La carga útil JSON de la respuesta también incluirá un next_token si hay páginas adicionales de datos. Para recopilar el conjunto completo de Posts coincidentes, independientemente del número de páginas, se deben realizar solicitudes hasta que no se proporcione un next_token. Por ejemplo, esta es una solicitud inicial de Posts con la palabra clave snow de la última semana: https://api.x.com/2/tweets/search/recent?query=snow La respuesta incluye los 10 Posts más recientes, junto con estos atributos «meta» en la respuesta JSON: 
"meta": {
        "newest_id": "1204860593741553664",
        "oldest_id": "1204860580630278147",
        "next_token": "b26v89c19zqg8o3fobd8v73egzbdt3qao235oql",
        "result_count": 10
    }
Para recuperar las 10 siguientes Posts, este next_token se agrega a la solicitud original. La solicitud sería: https://api.x.com/2/tweets/search/recent?query=snow&next_token=b26v89c19zqg8o3fobd8v73egzbdt3qao235oql El proceso de buscar un next_token e incluirlo en una solicitud posterior se puede repetir hasta que se recopilen todas (o cierta cantidad de) Posts, o hasta que se haya realizado un número específico de solicitudes. Si la fidelidad de los datos (recopilar todas las coincidencias de tu consulta) es clave para tu caso de uso, bastará con un diseño simple de “repetir hasta que request.next_token sea null”.

​
Casos de uso de sondeo y escucha

Esta sección explica cómo recuperar Posts recientes sondeando el endpoint de búsqueda reciente con el parámetro de solicitud since_id.  En los casos de uso de sondeo, se realizan de forma continua y frecuente consultas del tipo “¿hay nuevos Posts de interés?”. A diferencia de los casos de uso históricos, que basan las solicitudes en el tiempo, los casos de uso de sondeo suelen basarlas en los IDs de Post. En el patrón de sondeo es fundamental que cada nuevo Post tenga un ID único que se “emite” desde la plataforma de X generalmente en orden ascendente. Si un Post tiene un ID menor que otro, significa que se publicó antes. El endpoint de búsqueda reciente permite navegar por el archivo de Posts mediante el ID de Post. Las respuestas del endpoint incluyen los IDs de Post oldest_id y newest_id. En el modo de sondeo, las solicitudes se realizan con since_id establecido en el ID más grande/más reciente recibido hasta el momento.  Por ejemplo, supongamos que se realiza una consulta de nuevos Posts sobre nieve cada cinco minutos y que el último Post que recibimos tenía un ID de Post de 10000. Cuando corresponde sondear, la solicitud se ve así: https://api.x.com/2/tweets/search/recent?query=snow&since_id=10000 A continuación, supongamos que se publicaron siete Posts desde nuestra última solicitud. Como todos caben en una sola “página” de data, no hay next_token. La respuesta proporciona el ID de Post del Post más reciente (más nuevo): 
"meta": {
        "newest_id": "12000",
        "oldest_id": "10005",
        "result_count": 7
    }
Para realizar la siguiente consulta de sondeo, este valor de newest_id se utiliza para establecer el siguiente parámetro since_id: https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000 Cuando hay más datos disponibles y se proporcionan next tokens, solo se necesita el valor de newest_id de la primera página de resultados. Cada página de data incluirá valores de newest_id y oldest_id, pero el valor proporcionado en la primera página es el único necesario para la siguiente solicitud de sondeo programado con regularidad. Por lo tanto, si está implementando un diseño de sondeo o buscando Posts por rango de ID, la lógica de paginación es ligeramente más compleja. Ahora supongamos que hay 18 Posts adicionales que coinciden. El endpoint respondería con esta respuesta inicial, con una página de data completa y un next_token para solicitar la siguiente página de data de este período de cinco minutos. También incluiría el ID del Post más reciente necesario para el siguiente intervalo de sondeo en cinco minutos. 
"meta": {
        "newest_id": "13800",
        "oldest_id": "12500",
        "next_token": "fnsih9chihsnkjbvkjbsc",
        "result_count": 10
    }
Para recopilar todos los datos que coincidan en este período de cinco minutos, incluye el next_token en tu siguiente solicitud, junto con el mismo valor de since_id que en la solicitud anterior. https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000&next_token=fnsih9chihsnkjbvkjbsc 
"meta": {
        "newest_id": "12300",
        "oldest_id": "12010",
        "result_count": 8
    }
Esta segunda respuesta proporciona las ocho publicaciones restantes y no incluye next_token. Ten en cuenta que no actualizamos nuestro valor de newest_id (12300) y, en su lugar, basamos nuestra siguiente solicitud since_id en el valor de newest_id de la primera respuesta: https://api.x.com/2/tweets/search/recent?query=snow&since_id=13800