Vai al contenuto principale

​
Come integrare gli endpoint di Search Posts

Questa pagina contiene informazioni su diversi strumenti e concetti chiave da conoscere quando integri nel tuo sistema gli endpoint di ricerca recente o di ricerca nell’archivio completo. Abbiamo suddiviso la pagina nelle seguenti sezioni:

​
Strumenti utili

Prima di iniziare a esplorare alcuni concetti chiave, consigliamo di utilizzare uno dei seguenti strumenti o esempi di codice per iniziare a testare la funzionalità di questi endpoint.

​
Esempi di codice

Vuoi iniziare a usare questi endpoint con del codice nel linguaggio che preferisci? Sul nostro repository GitHub trovi diversi esempi di codice da usare come punto di partenza, inclusi un client Python e un client Ruby.

​
Librerie

Sfrutta una delle nostre numerose librerie di terze parti della community per iniziare. Puoi trovare una libreria compatibile con gli endpoint v2 cercando l’apposito tag di versione.

​
Postman

Postman è un ottimo strumento che puoi usare per testare questi endpoint. Ogni richiesta in Postman include tutti i parametri dell’endpoint in questione per aiutarti a capire rapidamente cosa hai a disposizione. Per saperne di più sulle nostre collection di Postman, visita la pagina Utilizzo di Postman.  

​
Concetti fondamentali

​
Autenticazione

Tutti gli endpoint di X API v2 richiedono di autenticare le richieste con un set di credenziali, note anche come chiavi e token. Puoi utilizzare OAuth 1.0a User Context, OAuth 2.0 App-Only oppure OAuth 2.0 Authorization Code with PKCE per autenticare le richieste all’endpoint di ricerca recente. Devi utilizzare OAuth 2.0 App-Only quando usi l’endpoint di ricerca dell’archivio completo. 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 per sviluppatori oppure generarne uno usando l’endpoint POST oauth2/token. OAuth 1.0a User Context richiede di utilizzare le tue API Keys, i Token di accesso utente e altri parametri per creare un’intestazione di autorizzazione, che poi includerai nella richiesta. I Token di accesso devono essere associati all’utente per conto del quale stai effettuando la richiesta. Se desideri generare un set di Token di accesso per un altro utente, quest’ultimo deve autorizzare la tua App utilizzando il flusso OAuth a 3 fasi. Tieni presente che OAuth 1.0a può essere complesso da utilizzare. Se non hai familiarità con questo metodo di autenticazione, ti consigliamo di usare una libreria, uno strumento come Postman oppure OAuth 2.0 per autenticare le richieste. Se desideri richiedere un Post o metriche private da questi endpoint, dovrai utilizzare OAuth 1.0a User Context oppure OAuth 2.0 Authorization Code with PKCE, che garantiranno le autorizzazioni appropriate da parte dell’utente proprietario di quel contenuto. OAuth 2.0 Authorization Code with PKCE consente un controllo più granulare sull’ambito di un’applicazione e flussi di autorizzazione su più dispositivi. OAuth 2.0 ti consente di scegliere ambiti specifici e dettagliati che ti concedono permessi precisi per conto di un utente. Per abilitare OAuth 2.0 nella tua App, devi attivarlo nelle impostazioni di autenticazione della tua App, nella sezione delle impostazioni dell’App del portale sviluppatori.
Nota beneSe stai richiedendo i seguenti campi, è richiesto OAuth 1.0a User Context 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

​

Portale sviluppatori, Progetti e App per sviluppatori Per utilizzare qualsiasi endpoint di X API v2, devi registrarti per un account sviluppatore, creare un Progetto all’interno di tale account e un’App per sviluppatori all’interno di quel Progetto. Le chiavi e i token dell’App per sviluppatori funzioneranno con questi endpoint di ricerca. Puoi utilizzare chiavi e token di un Progetto con qualsiasi livello di accesso per inviare richieste all’endpoint di ricerca recente. Tuttavia, per inviare richieste all’endpoint di ricerca dell’archivio completo dovrai utilizzare un Progetto con livello di accesso Pro o Enterprise. Se disponi di accesso Enterprise, avrai funzionalità aggiuntive, inclusi operatori aggiuntivi e query più lunghe.  

​
Limiti di velocità

Ogni giorno, migliaia di sviluppatori inviano richieste alla X API. Per gestire il volume, su ciascun endpoint vengono applicati limiti di velocità che riducono 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à diversi, a seconda del metodo di autenticazione utilizzato. I limiti di velocità a livello di app si applicano a un’app che effettua richieste usando OAuth 2.0 App-Only, mentre il limite a livello utente si applica alle richieste effettuate per conto dello specifico utente autorizzante usando OAuth 1.0a User Context o OAuth 2.0 Authorization Code with PKCE. Entrambi i limiti si basano sulla frequenza delle richieste all’interno di una finestra di 15 minuti. Ad esempio, un’app che utilizza l’autenticazione OAuth 2.0 App-Only per effettuare richieste all’endpoint di ricerca recente può effettuare 450 richieste (incluse quelle di paginazione) in un intervallo di 15 minuti. La stessa app, nello stesso intervallo di 15 minuti e con due diversi utenti autenticati (usando OAuth 1.0a User Context o OAuth 2.0 Authorization Code with PKCE), può effettuare fino a 180 richieste (incluse quelle di paginazione) all’endpoint di ricerca recente per ciascun utente autenticato.  

​
Campi ed espansioni

X API v2 consente di selezionare con precisione quali dati ottenere dall’API utilizzando campi ed espansioni. Il parametro expansions consente di restituire come oggetti completi quelli referenziati nel payload. Ad esempio, questo endpoint permette di richiedere oggetti come poll, place, media e altri tramite il parametro expansions. I parametri dei campi consentono di scegliere esattamente quali campi dei diversi oggetti dati ricevere. Per impostazione predefinita, l’oggetto Post principale restituito da questi endpoint include i campi id e text (oltre a edit_history_tweet_ids per i Post creati dopo l’introduzione di tale funzionalità). Per ottenere campi aggiuntivi come author_id o public_metrics, è necessario richiederli esplicitamente utilizzando i parametri dei campi. Alcuni campi importanti da considerare nella propria integrazione sono i dati dei poll, le metriche, le annotazioni dei Post e i campi dell’conversation ID. Abbiamo aggiunto una guida su come utilizzare congiuntamente campi ed espansioni nel nostro dizionario dei dati di X API v2.  

​
Metriche

Gli endpoint di X API v2 consentono di richiedere metriche direttamente dagli oggetti restituiti, a condizione che tu includa nella richiesta i campi appropriati. Esistono alcune limitazioni relative alle metriche dei Post che dovresti conoscere, in particolare per quanto riguarda la privacy degli utenti e i seguenti campi 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 campi indicati includono dati di metriche private; ciò significa che devi essere autorizzato dal publisher del Post per recuperare tali dati per suo conto quando utilizzi l’endpoint di ricerca recente, e quindi devi usare OAuth 1.0a User Context. Poiché questo metodo di autenticazione è disponibile solo con la ricerca recente, non potrai recuperare queste metriche tramite l’endpoint di ricerca dell’archivio completo. Ad esempio, per ricevere non_public_metrics per i Post dell’utente con id 1234, dovrai includere nella richiesta i Token di accesso associati a quell’utente. Puoi fare in modo che gli utenti autorizzino la tua app e ottenere un set di Token di accesso a loro associati utilizzando il flusso OAuth a 3 fasi. Tutte le non_public_metrics, le organic_metrics e le promoted_metrics sono disponibili solo per i Post creati negli ultimi 30 giorni. Ciò significa che, quando richiedi i campi indicati, i risultati si adatteranno automaticamente includendo solo i Post degli ultimi 30 giorni. Se vengono richiesti questi campi, verranno restituiti solo i Post creati dall’utente autenticato; per tutti gli altri Post verrà restituito un messaggio di errore.  

​
Creazione di query di ricerca

La funzionalità principale di questi endpoint è l’uso di un’unica query di ricerca per filtrare i Post consegnati all’utente. Queste query sono composte da operatori che fanno corrispondere attributi dei Post e degli utenti, come parole chiave del messaggio, hashtag e URL. Gli operatori possono essere combinati in query con logica booleana e parentesi per affinare il comportamento di corrispondenza della query. Puoi consultare la nostra guida su come creare una query per saperne di più. Questi endpoint utilizzano la paginazione per restituire rapidamente le risposte. Quando i risultati superano il numero che può essere inviato in un’unica risposta (fino a 100 Post per la ricerca recente e 500 per la ricerca nell’archivio completo), è necessario paginare. Usa il parametro max_results per specificare quanti risultati restituire per pagina e il parametro pagination_token per ottenere la pagina successiva di risultati. Per maggiori dettagli, consulta la nostra guida alla paginazione.

​
Limiti ai Post

Gli endpoint di Search Posts sono soggetti a un limite mensile del numero di Post che possono restituire, indipendentemente dalla paginazione. Indipendentemente dall’endpoint di ricerca utilizzato, i Post restituiti verranno conteggiati rispetto ai limiti ai Post a livello di Progetto. L’utilizzo è visibile nel portale sviluppatori e il “mese” inizia nel giorno di rinnovo dell’abbonamento indicato nella dashboard del portale sviluppatori. Modifiche ai Post I Post idonei alla modifica 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 da 30 o più minuti, 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 la ricezione. Questi Post possono essere reidratati tramite 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 Fondamenti delle modifiche ai Post.   Prossimi passi Effettua la tua prima richiesta a un endpoint di Search Posts Consulta l’elenco completo di parametri, campi e altro nelle nostre pagine di riferimento dell’API Ottieni supporto o risolvi un errore