Vai al contenuto principale

​
Introduzione

La paginazione è una funzionalità degli endpoint di X API v2 che restituiscono più risultati di quanti se ne possano includere in una singola risposta. In questi casi, i dati vengono restituiti in una serie di “pagine”. Per paginazione si intendono i metodi che consentono di richiedere programmaticamente tutte le pagine per recuperare l’intero set di risultati. Non tutti gli endpoint API supportano o richiedono la paginazione, ma è spesso impiegata quando i set di risultati sono di grandi dimensioni.

​
Casi d’uso della paginazione

Per ottenere tutti i risultati di una richiesta: Utilizzare la paginazione per ricevere tutti i dati pertinenti relativi a una specifica richiesta e ai relativi parametri. La paginazione è necessaria quando i risultati corrispondenti superano il valore di max_results per una richiesta. Iterare le richieste con i token di paginazione consente di recuperare tutti i risultati. Quando una risposta viene restituita senza un valore next_token, si può presumere che tutti i risultati siano stati paginati. La paginazione non va usata per il polling. Per ottenere i risultati più recenti rispetto a una richiesta precedente, consultare il polling con since_id. Per scorrere i risultati di una richiesta: La paginazione offre opzioni direzionali per navigare tra i risultati di una richiesta, utilizzando i valori next_token e previous_token presenti nelle risposte. Questi token possono essere impostati come pagination_token nella richiesta successiva per passare alla pagina successiva o precedente dei risultati.

​
Definizioni dei token di paginazione

  • next_token - Stringa opaca restituita all’interno dell’oggetto meta nella risposta sugli endpoint che supportano la paginazione. Indica che sono disponibili altri risultati e può essere usata come parametro pagination_token nella richiesta successiva per ottenere la pagina seguente di risultati. L’ultima pagina di risultati non conterrà un next_token.
    • previous_token - Stringa opaca restituita all’interno dell’oggetto meta nella risposta sugli endpoint che supportano la paginazione. Indica che è disponibile una pagina precedente di risultati e può essere impostata come parametro pagination_token nella richiesta successiva per ottenere la pagina precedente di risultati.
    • pagination_token - Parametro utilizzato nelle richieste di paginazione. Impostalo al valore di next_token per la pagina successiva di risultati. Impostalo al valore di previous_token per la pagina precedente di risultati.

​
Fondamenti della paginazione

  • Gli endpoint che utilizzano la paginazione rispondono a una richiesta iniziale con la prima pagina di risultati e, se sono disponibili pagine aggiuntive, forniscono un next_token all’interno dell’oggetto meta nella risposta JSON. Per ricevere tutti i risultati, ripetere questo processo finché nella risposta non è più incluso alcun next_token.
    • I risultati vengono restituiti in ordine cronologico inverso. Questo vale sia all’interno delle singole pagine sia tra più pagine:
      • Il primo Post nella prima risposta sarà il più recente.
      • L’ultimo Post nell’ultima risposta sarà il più vecchio.
    • Il parametro di richiesta max_results consente di impostare il numero di Post restituiti per pagina. Sono previsti un valore predefinito e un valore massimo per max_results.
    • Ogni implementazione della paginazione comporta l’estrazione dei token dal payload della risposta, che possono essere utilizzati nelle richieste successive.
    • In alcune circostanze, potresti ottenere meno elementi del valore di max_results per pagina. Non dare per scontato che i risultati per pagina coincidano sempre con il valore del parametro max_results.
    • I modi migliori per ottenere risultati completi con la paginazione sono usare una logica a loop nel codice di integrazione oppure una libreria che supporti X API v2.

​
Esempio di paginazione

Qui sono presenti tre pagine di risultati perché max_results è impostato su 100 e ci sono circa 295 Post creati dall’utente con id 2244994945 (@XDevelopers) tra il 1º gennaio 2019 alle 17:00:00 UTC e il 12 dicembre alle 00:00:00 UTC. Il primo Post nella prima pagina (1337498609819021312) è il più recente, e l’ultimo Post nella terza pagina dei risultati (1082718487011885056) è il meno recente.

​
Richiesta iniziale

      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

​
Tabella delle sequenze

Prima richiestaSeconda paginaTerza paginaQuarta pagina
Parametri della richiesta- 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
Rispostajson { "data": [ { "created_at": "2020-12-11T20:44:52.000Z", "id": "1337498609819021312", "text": "Grazie a tutti coloro che si sono collegati oggi..." }, ... , { "created_at": "2020-05-06T17:24:31.000Z", "id": "1258085245091368960", "text": "Ora è più facile comprendere l’impatto dei 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": "La nostra community di sviluppatori è ricca di idee stimolanti..." }, ... , { "created_at": "2019-11-21T16:17:23.000Z", "id": "1197549579035496449", "text": "Presto rilasceremo strumenti per..." } ], "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": "Sappiamo che alcune persone che ricevono un elevato volume di risposte possono..." }, ... , { "created_at": "2019-01-08T19:19:37.000Z", "id": "1082718487011885056", "text": "Aggiornamenti agli embed 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" } }
Azioni da intraprendere per la prossima richiestaPer ottenere la pagina successiva, prendi il valore di next_token direttamente dalla risposta (7140w) e impostalo come pagination_token per la chiamata successiva.Per continuare a ottenere tutti i risultati: prendi il valore di next_token direttamente dalla risposta (7140k9) e impostalo come pagination_token per la chiamata successiva. Per passare alla pagina precedente: prendi il valore di previous_token direttamente dalla risposta (77qp8) e impostalo come pagination_token per la chiamata successiva.Per continuare a ottenere tutti i risultati: prendi il valore di next_token direttamente dalla risposta (71408hi) e impostalo come pagination_token per la chiamata successiva. Per passare alla pagina precedente: prendi il valore di previous_token direttamente dalla risposta (77qplte) e impostalo come pagination_token per la chiamata successiva.Nota che non è presente alcun next_token, il che indica che tutti i risultati sono stati ricevuti. Per passare alla pagina precedente: prendi il valore di previous_token direttamente dalla risposta (77qpw8l) e impostalo come pagination_token per la chiamata successiva.
⌘I