Paginação do recent search
Introdução
Queries de busca geralmente correspondem a mais Posts do que pode ser retornado em uma única resposta da API. Quando isso acontece, os dados são retornados em uma série de ‘páginas’. Paginação refere-se aos métodos para solicitar todas as páginas a fim de recuperar todo o conjunto de dados. Aqui estão os detalhes fundamentais da paginação do recent search:- Os endpoints do recent search responderão a uma query com pelo menos uma página e fornecerão um next_token em sua resposta JSON se páginas adicionais estiverem disponíveis. Para receber os Posts correspondentes, este processo pode ser repetido até que nenhum token seja incluído na resposta.
- O next_token não expira. Múltiplas requisições usando o mesmo valor de next_token receberão os mesmos resultados, independentemente de quando a requisição for feita.
-
Os Posts são entregues em ordem cronológica inversa, no fuso horário UTC. Isso é verdade dentro de páginas individuais, bem como entre múltiplas páginas:
- O primeiro Post na primeira resposta será o mais recente que corresponde à sua query.
- O último Post na última resposta será o mais antigo que corresponde à sua query.
- O parâmetro de requisição max_results permite configurar o número de Posts retornados por resposta. O padrão é 10 Posts e o máximo é 100.
- Toda implementação de paginação envolverá extrair next_tokens do payload de resposta e incluí-los na requisição de busca da ‘próxima página’. Veja abaixo mais detalhes sobre como construir essas requisições de ‘próxima página’.
- Obter histórico - Solicitar Posts correspondentes de um período de interesse. Estas são tipicamente requisições únicas em apoio à pesquisa histórica. Requisições de busca podem ser baseadas nos parâmetros de requisição start_time e end_time. O endpoint recent search responde com Posts entregues em ordem cronológica inversa, começando com o Post correspondente mais recente.
- Polling - Solicitar Posts correspondentes que foram publicados desde o último Post recebido. Estes casos de uso frequentemente têm um foco em quase tempo real e são caracterizados por requisições frequentes, “escutando” novos Posts de interesse. O endpoint recent search fornece o parâmetro de requisição since_id em apoio ao padrão de ‘polling’. Para ajudar a navegar por IDs de Post, o parâmetro de requisição until_id também está disponível.
Recuperando dados históricos
Esta seção descreve como você pode recuperar Posts de um período de interesse (atualmente limitado aos últimos sete dias) usando os parâmetros de requisição start_time e end_time. Requisições históricas são tipicamente requisições únicas em apoio a pesquisa e análise. Fazer requisições para um período de dados é o modo padrão do endpoint recent search. Se uma requisição de busca não especificar um parâmetro de requisição start_time, end_time ou since_id, o end_time será por padrão “agora” (na verdade, 30 segundos antes do momento da query) e o start_time será por padrão sete dias atrás. O endpoint responderá com a primeira ‘página’ de Posts em ordem cronológica inversa, começando com o Post mais recente. O payload JSON da resposta também incluirá um next_token se houver páginas adicionais de dados. Para coletar o conjunto completo de Posts correspondentes, independentemente do número de páginas, requisições são feitas até que nenhum next_token seja fornecido. Por exemplo, aqui está uma requisição inicial para Posts com a palavra-chave snow da última semana: https://api.x.com/2/tweets/search/recent?query=snow A resposta inclui os 10 Posts mais recentes, junto com estes atributos “meta” na resposta JSON:Casos de uso de polling e listening
Esta seção descreve como você pode recuperar Posts recentes fazendo polling no endpoint recent search com o parâmetro de requisição since_id. Em casos de uso de polling, queries do tipo “algum novo Post de interesse?” são feitas de forma contínua e frequente. Diferentemente dos casos de uso históricos, que baseiam requisições em tempo, casos de uso de polling normalmente baseiam requisições em IDs de Post. Central para o padrão de uso de polling é o fato de que cada novo Post tem um ID único que é ‘emitido’ pela plataforma X geralmente em ordem crescente. Se um Post tem um ID menor que outro, isso significa que foi publicado antes. O endpoint recent search suporta navegar pelo arquivo de Posts por ID de Post. As respostas do endpoint incluem os IDs de Post oldest_id e newest_id. No modo de polling, as requisições são feitas com o since_id definido como o maior/mais novo ID recebido até o momento. Por exemplo, digamos que uma query para novos Posts sobre snow seja feita a cada cinco minutos, e o último Post que recebemos tinha um ID de Post de 10000. Na hora do polling, a requisição fica assim: https://api.x.com/2/tweets/search/recent?query=snow&since_id=10000 A seguir, digamos que sete Posts foram publicados desde nossa última requisição. Como todos cabem em uma única ‘página’ de dados, não há next_token. A resposta fornece o ID do Post mais recente (mais novo):https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000
Quando há mais dados disponíveis, e next_tokens são fornecidos, apenas o valor newest_id da primeira página de resultados é necessário. Cada página de dados incluirá valores newest_id e oldest_id, mas o valor fornecido na primeira página é o único necessário para a próxima requisição de polling programada regularmente. Portanto, se você estiver implementando um design de polling ou pesquisando Posts por intervalo de ID, a lógica de paginação é um pouco mais complicada.
Agora, digamos que existem mais 18 Posts correspondentes. O endpoint responderia com esta resposta inicial com uma página completa de dados e um next_token para solicitar a próxima página de dados deste período de cinco minutos. Também incluiria o Post ID mais novo necessário para o próximo intervalo de polling em cinco minutos.