Vai al contenuto principale

​
Come integrare gli endpoint Timelines

Questa pagina contiene informazioni su diversi strumenti e concetti chiave che dovresti conoscere quando integri gli endpoint Timelines nel tuo sistema. Abbiamo suddiviso la pagina nelle seguenti sezioni:

​
Strumenti utili

Prima di approfondire alcuni concetti chiave, ti consigliamo di utilizzare uno dei seguenti strumenti o esempi di codice per iniziare a testare le funzionalità di questi endpoint. Esempi di codice Vuoi configurare questi endpoint con del codice nel tuo linguaggio di programmazione preferito? Mettiamo a disposizione diversi esempi di codice che puoi usare come punto di partenza nella nostra pagina GitHub. Librerie Sfrutta una delle nostre numerose librerie di terze parti della community per iniziare. Puoi trovare una libreria compatibile con gli endpoint v2 cercando il tag di versione appropriato. Postman Postman è un ottimo strumento per testare questi endpoint. Ogni richiesta Postman include tutti i parametri di percorso (path) e del corpo (body) per aiutarti a comprendere rapidamente ciò che è disponibile. Per saperne di più sulle nostre raccolte Postman, visita la pagina Utilizzare Postman.

​
Concetti chiave

Autenticazione Tutti gli endpoint di X API v2 richiedono che le richieste siano autenticate con un set di credenziali, note anche come chiavi e token. Puoi utilizzare Contesto utente OAuth 1.0a oppure OAuth 2.0 Authorization Code con PKCE per autenticare le richieste a questi endpoint. Puoi utilizzare OAuth 2.0 App-Only per la timeline dei Post di un utente e per la timeline delle menzioni dell’utente. Contesto utente OAuth 1.0a richiede di utilizzare le tue API Key, gli Access Tokens dell’utente e alcuni altri parametri per creare un’intestazione di autorizzazione, che poi invierai insieme alla richiesta. Gli Access Tokens devono essere associati all’utente per conto del quale stai effettuando la richiesta. Se desideri generare un set di Access Tokens per un altro utente, quest’ultimo deve autorizzare la tua App utilizzando il flusso OAuth a 3 vie. Tieni presente che OAuth 1.0a può essere complesso da utilizzare. Se non conosci questo metodo di autenticazione, ti consigliamo di usare una libreria, uno strumento come Postman o OAuth 2.0 per autenticare le richieste. Se desideri richiedere un Post o metriche private da questi endpoint, dovrai utilizzare Contesto utente OAuth 1.0a oppure OAuth 2.0 Authorization Code con PKCE, in modo da garantire le autorizzazioni appropriate dall’utente proprietario di quel contenuto. OAuth 2.0 App-Only richiede semplicemente di includere un OAuth 2.0 App Access Token nella richiesta. Puoi generare un App Access Token direttamente all’interno di un’App sviluppatore oppure generarne uno utilizzando l’endpoint POST oauth2/token. Puoi usarlo per la timeline dei Post dell’utente o per la timeline delle menzioni dell’utente. OAuth 2.0 Authorization Code con PKCE consente un maggiore controllo sugli scope dell’applicazione e flussi di autorizzazione su più dispositivi. OAuth 2.0 ti permette di selezionare scope granulari che concedono specifiche autorizzazioni per conto di un utente. Per abilitare OAuth 2.0 nella tua App, devi abilitarlo nelle impostazioni di autenticazione della tua App, nella sezione delle impostazioni dell’App del developer portal.
Nota beneSe richiedi i seguenti fields, è necessario Contesto utente OAuth 1.0a oppure OAuth 2.0 Authorization Code:
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
Developer portal, Project e App sviluppatore Per lavorare con qualsiasi endpoint di X API v2, devi registrare un account sviluppatore, configurare un Project all’interno di tale account e creare un’App sviluppatore all’interno di quel Project. Le chiavi e i token presenti in quell’App sviluppatore funzioneranno per questi endpoint delle timeline. Limiti di velocità Ogni giorno, molte migliaia di sviluppatori inviano richieste alla X API. Per gestire il volume, vengono applicati limiti di velocità a ciascun endpoint che limitano il numero di richieste che ogni sviluppatore può effettuare per conto di un’App o di un utente autenticato. A questi endpoint si applicano limiti di velocità differenti a seconda del metodo di autenticazione utilizzato. I limiti di velocità a livello di app si applicano a un’App che effettua richieste utilizzando OAuth 2.0 App-Only, mentre il limite di velocità a livello di utente si applica alle richieste effettuate per conto dello specifico utente autorizzante utilizzando Contesto utente OAuth 1.0a. Entrambi i limiti si basano sulla frequenza delle richieste in una finestra di 15 minuti. Ad esempio, un’app che utilizza l’autenticazione OAuth 2.0 App-Only per entrambi questi endpoint delle timeline può effettuare 1500 richieste (incluse quelle di paginazione) alla timeline dei Post dell’utente e 450 richieste (incluse quelle di paginazione) alla timeline delle menzioni dell’utente in un intervallo di 15 minuti. La stessa app, nello stesso intervallo di 15 minuti, con due utenti autorizzati diversi (utilizzando il Contesto utente OAuth 1.0a) può effettuare 900 richieste (incluse quelle di paginazione) alla timeline dei Post dell’utente e 180 richieste (incluse quelle di paginazione) alla timeline delle menzioni dell’utente per ciascun utente autenticato. La home timeline in ordine cronologico inverso ha un limite di velocità per utente di 180 richieste per finestra di 15 minuti. Con questo endpoint puoi ottenere tutti i Post creati su una timeline negli ultimi 7 giorni, nonché gli ultimi 800 indipendentemente dalla data di creazione. Fields and expansions La X API v2 consente di selezionare esattamente quali data desideri ricevere dall’API utilizzando fields ed expansions. Il parametro expansions consente di includere gli oggetti referenziati nel payload. Ad esempio, questo endpoint consente di richiedere oggetti poll, place, media e altri utilizzando il parametro expansions. Il parametro fields consente di selezionare esattamente quali fields all’interno dei diversi oggetti di data desideri ricevere. Per impostazione predefinita, l’Oggetto Post principale restituito da questi endpoint include i fields id e text. Per ricevere fields aggiuntivi come author_id o public_metrics, dovrai richiederli esplicitamente utilizzando i parametri fields. Alcuni fields importanti che potresti prendere in considerazione nella tua integrazione sono i nostri data relativi ai poll, le metriche, le Post annotations e i fields di conversation ID. Abbiamo aggiunto una guida su come utilizzare fields ed expansions insieme al nostro X API v2 data dictionary. Post metrics Gli endpoint della X API v2 consentono di richiedere le metriche dei Post direttamente dall’Oggetto Post restituito, a condizione che tu includa i fields appropriati nella richiesta. Esistono alcune limitazioni relative alle metriche dei Post di cui dovresti essere a conoscenza, in particolare legate alla privacy degli utenti e ai seguenti fields di risposta:
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
I fields indicati includono metriche private, il che significa che devi essere autorizzato dal publisher del Post per recuperare questi data per loro conto quando utilizzi l’endpoint della timeline dei Post dell’utente; pertanto devi usare il Contesto utente OAuth 1.0a o l’OAuth 2.0 Authorization Code Flow with PKCE. Ad esempio, per ricevere i non_public_metrics per la timeline dei Post dell’utente con ID 1234 dovrai includere nella richiesta gli access token associati a quell’utente. Puoi far autorizzare la tua App dagli utenti e ottenere un set di access token a loro associati utilizzando il flusso OAuth a 3 vie. Se stai utilizzando la timeline delle menzioni dell’utente, i fields indicati non saranno disponibili a meno che l’autore che menziona non abbia autorizzato la tua App ad accedere alle proprie metriche private e tu stia utilizzando gli access token di quell’utente quando effettui la richiesta con il Contesto utente OAuth 1.0a. Tutti i non_public_metrics, organic_metrics e promoted_metrics sono disponibili solo per i Post creati negli ultimi 30 giorni. Ciò significa che quando richiedi i fields indicati, i risultati si adatteranno automaticamente per includere solo i Post degli ultimi 30 giorni. Se vengono richiesti questi fields, verranno restituiti solo i Post creati dall’utente autenticato; tutti gli altri Post restituiranno un messaggio di errore. Pagination Questi endpoint utilizzano la paginazione per restituire rapidamente le risposte. Nei casi in cui ci siano più risultati di quanti ne possano essere inviati in una singola risposta (fino a 100 Post per gli endpoint delle timeline) dovrai applicare la paginazione. Utilizza il parametro max_results per indicare quanti risultati verranno restituiti per pagina e il parametro pagination_token per ottenere la pagina successiva di risultati. Puoi saperne di più consultando la nostra guida alla paginazione. Filtrare i risultati Questi endpoint includono diversi parametri che puoi utilizzare per filtrare i risultati. Utilizzando start_time ed end_time, puoi restringere i risultati a un intervallo di tempo specifico. Se preferisci utilizzare gli ID dei Post per selezionare un insieme specifico di Post, puoi usare since_id e until_id. La timeline dei Post dell’utente include anche un parametro exclude che può rimuovere i Retweet e le risposte dai risultati.  Post cap e volume di Post restituiti Gli endpoint della timeline dei Post dell’utente e della timeline delle menzioni dell’utente sono limitati nel numero di Post che possono restituire in un determinato mese. L’endpoint della timeline home in ordine cronologico inverso non è soggetto a questa limitazione. Indipendentemente da quale endpoint di timeline utilizzi, i Post restituiti saranno conteggiati ai fini dei Post cap a livello di Project Post caps. L’utilizzo è mostrato nel developer portal e il “mese” inizia nel giorno di rinnovo dell’abbonamento indicato nella dashboard del developer portal.  L’endpoint della timeline dei Post dell’utente restituirà solo i 3200 Post più recenti pubblicati nella timeline di un utente. Impostando start_time ed end_time su un periodo che include Post oltre i 3200 più recenti, riceverai una risposta con esito positivo, ma nessun Post. È inoltre importante notare che, se invii excludes=replies con le richieste alla timeline dei Post dell’utente, saranno restituiti solo gli 800 Post più recenti. L’endpoint della timeline delle menzioni dell’utente restituirà solo le 800 menzioni di Post più recenti. L’endpoint della timeline home in ordine cronologico inverso restituisce gli ultimi 3200 Post. Modifiche ai Post I Post idonei alle modifiche possono essere modificati fino a cinque volte nei 30 minuti successivi alla pubblicazione del Post originale. Gli endpoint di ricerca forniranno sempre la versione più recente del Post. Se richiedi solo Post pubblicati 30 o più minuti fa, riceverai sempre la versione finale del Post. Tuttavia, se hai un caso d’uso quasi in tempo reale e stai interrogando Post pubblicati negli ultimi trenta minuti, quei Post potrebbero essere stati modificati dopo che li hai ricevuti. Questi Post possono essere reidratati con la ricerca o con l’endpoint Post Lookup per confermarne lo stato finale. Per saperne di più su come funzionano le modifiche ai Post, consulta la pagina Nozioni fondamentali sulle modifiche ai Post.   Casi limite
  • Quando richiedi metriche non pubbliche sull’endpoint User Post timeline per Post più vecchi di 30 giorni, potresti vedere un next_token nella risposta con un numero di risultati pari a 0. Per evitare questo problema, assicurati che l’intervallo di tempo richiesto con il parametro non_public_metrics rientri negli ultimi 30 giorni. Inoltre, il valore minimo di max_results dovrebbe essere 10. Questi accorgimenti possono aiutare a evitare questo scenario, ma potrebbe comunque verificarsi.
  • Richiedere metriche promosse per Post che non sono stati promossi restituisce una risposta vuota, invece dei dati del Post. Il nostro team sta attualmente lavorando per risolvere questo problema.
  • Per un Retweet che contiene testo del corpo del Post superiore a 140 caratteri, il campo text verrà troncato invece di restituire il testo completo del Post. La soluzione temporanea consiste nell’espandere il Post referenziato e recuperare il testo completo dall’espansione. Questo è un bug che correggeremo in futuro.
Prossimi passi [Make your first request to a Timelines endpoint]/x-api/posts/timelines#getting-started-with-reverse-chronological-home-timeline “Make your first request to a Timelines endpoint”) Vedi l’elenco completo di parametri, fields e altro nelle nostre pagine di riferimento dell’API Ottieni supporto o risolvi un errore
⌘I