Vai al contenuto principale
Gli endpoint di X API v2 dispongono di un set di parametri chiamati fields, che consentono di selezionare solo i dati desiderati da ciascuno degli oggetti nella risposta dell’endpoint. Per impostazione predefinita, l’Oggetto Post restituisce solo i campi id e text e, per i Post creati dal 29 settembre 2022, il campo edit_history_tweet_ids. Se servono la data di creazione del Post o le metriche pubbliche, è necessario usare il parametro tweet.fields per richiederle. Questo offre un livello più elevato di personalizzazione consentendo di richiedere solo i campi necessari in base al caso d’uso. Ad esempio, si includerebbe questa stringa di query nella richiesta: ?tweet.fields=created_at,public_metrics Ogni oggetto ha il proprio parametro per richiedere specificamente i campi associati a quell’oggetto. Ecco i diversi parametri di fields attualmente disponibili:
  • Post → tweet.fields
  • User → user.fields
  • Media → media.fields
  • Poll → poll.fields
  • Place → place.fields
Quando si utilizza un endpoint che restituisce principalmente un determinato oggetto, usare il parametro di fields corrispondente e specificare i campi desiderati in un elenco separato da virgole come valore di quel parametro, per recuperarli nella risposta.

​
Esempio

Se utilizzi l’endpoint GET /tweets/search/recent, nella risposta riceverai principalmente oggetti Tweet. Senza specificare alcun parametro fields, riceverai solo i valori predefiniti, id e text. Se desideri ottenere le metriche pubbliche dei Post restituiti nella risposta, includi il parametro tweet.fields nella tua richiesta, impostando public_metrics come valore. Questa richiesta sarà simile alla seguente. Se desideri utilizzarla, assicurati di sostituire $BEARER_TOKEN con il tuo Bearer Token e inviala tramite il tuo strumento da riga di comando. 
curl --request GET \
  --url 'https://api.x.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics' \
  --header 'Authorization: Bearer $BEARER_TOKEN'
Se invii questa richiesta dal terminale, ciascuno dei Post restituiti includerà i seguenti fields: 
{
   "data": {
       "id": "1263150595717730305",
       "public_metrics": {
           "retweet_count": 12,
           "reply_count": 14,
           "like_count": 49,
           "quote_count": 7
       },
       "text": "Hai visto 👀 le nostre nuove impostazioni per i Tweet?\n\nVogliamo sapere come e perché utilizzeresti una funzionalità del genere nell'API. Scopri i dettagli e facci sapere cosa ne pensi👇\nhttps://t.co/RtMhhfAcIB https://t.co/8wxeZ9fJER"
   }
}
Se desideri recuperare un insieme di fields da un oggetto secondario associato all’oggetto primario restituito da un endpoint, devi includere un parametro expansions aggiuntivo. Ad esempio, se stessi usando lo stesso endpoint GET search/tweets/recent di prima e volessi ottenere la descrizione del profilo dell’autore, dovrai passare expansions=author_id e user.fields=description nella tua richiesta. Ecco un esempio di come potrebbe essere. Se desideri provare questa richiesta, assicurati di sostituire $BEARER_TOKEN con il tuo Bearer Token prima di incollarla nel tuo strumento da riga di comando. 
  curl --request GET \
  --url 'https://api.x.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics&expansions=author_id&user.fields=description' \
  --header 'Authorization: Bearer $BEARER_TOKEN'
Se lo specifichi nella richiesta, ciascuno dei Post restituiti includerà i seguenti fields e i campi predefiniti e quelli specificati dell’oggetto utente verranno restituiti all’interno di includes. L’oggetto utente può essere ricondotto al/i Post corrispondente/i abbinando tweet.author_id e il campo users.id. 
{
  "data": [
    {
      "id": "1263150595717730305",
      "author_id": "2244994945",
      "text": "Hai visto 👀 le nostre nuove impostazioni per i Tweet?\n\nVogliamo sapere come e perché utilizzeresti una funzionalità del genere nell'API. Scopri i dettagli e facci sapere cosa ne pensi👇\nhttps://t.co/RtMhhfAcIB https://t.co/8wxeZ9fJER",
      "public_metrics": {
        "retweet_count": 12,
        "reply_count": 13,
        "like_count": 51,
        "quote_count": 7
      }
    }
  ],
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "username": "TwitterDev",
        "description": "La voce del team #TwitterDev e la tua fonte ufficiale per aggiornamenti, notizie ed eventi relativi alla #TwitterAPI.",
        "name": "Twitter Dev"
      }
    ]
  }
}
Tieni presente che non puoi richiedere sottofield specifici (ad esempio public_metrics.retweet_count). Tutti i sottofield verranno restituiti quando viene specificato il field di livello superiore (public_metrics). Abbiamo elencato tutti i possibili fields che puoi richiedere nella tabella dei parametri della pagina di riferimento API di ciascun endpoint. Un elenco completo dei fields è disponibile nel modello di oggetti. Per includere e richiedere fields su un oggetto che non è la risorsa primaria di quell’endpoint, usa il parametro expansions insieme ai fields.
⌘I