Guida rapida

​

Introduzione agli endpoint del filtered stream

Questa guida di Avvio rapido ti aiuterà a inviare la tua prima richiesta al gruppo di endpoint del filtered stream utilizzando cURL. cURL è uno strumento da riga di comando che consente di effettuare richieste con una configurazione minima.

Se desideri consultare esempi di codice in linguaggi diversi, visita il nostro repository GitHub X API v2 sample code. 

Prerequisiti

Per completare questa guida, devi disporre di un set di chiavi e token per autenticare la tua richiesta. Puoi generare queste chiavi e questi token seguendo i passaggi indicati di seguito:

• Registrati per un account sviluppatore e attendi l’approvazione.
• Crea un Project e una App sviluppatore associata nel developer portal.
• Vai alla pagina “Keys and tokens” della tua App per generare le credenziali richieste. Assicurati di conservare tutte le credenziali in un luogo sicuro.

​

Passaggi per creare una richiesta filtered stream con cURL

Passaggio uno: crea una regola

Le regole sono composte da uno o più operatori, combinati usando logica booleana e parentesi per definire quali Post verranno recapitati al tuo stream. In questa guida filtreremo lo stream per trovare Post che contengano sia la parola chiave “cat” sia immagini. Ecco la nostra regola:

has:images

Secondo passaggio: aggiungi un tag alla tua regola

Puoi aggiungere più regole contemporaneamente al tuo stream. Quando apri la connessione di streaming, i Post che corrispondono a una qualsiasi di queste regole passeranno attraverso la stessa connessione. Per identificare quale Post corrisponde a quale regola, puoi includere un tag nella richiesta di creazione della regola. Ogni Post che corrisponde a quella regola includerà quindi un campo tag all’interno del payload del Post che indica a quale regola è associato. Per questa regola, assegneremo il seguente tag:

with images

Passaggio tre: aggiungi la regola allo stream

Questo endpoint richiede di inviare, insieme a questa richiesta, un body con tipo application/JSON che contenga la regola e il relativo tag. Noterai anche che abbiamo incluso il valore della regola e il tag all’interno di un oggetto add, poiché stiamo aggiungendo questa regola allo stream. Questo body JSON avrà il seguente aspetto:

{
  "add": [
    {
      "value": "cat has:images",
      "tag": "gatti con immagini"
    }
  ]
}

Ora che hai configurato completamente questo body JSON, puoi aggiungerlo a una richiesta cURL, che avrà il seguente aspetto. Questa richiesta non è ancora pronta, quindi attendi a inviarla fino a un passaggio successivo.

curl -X POST 'https://api.x.com/2/tweets/search/stream/rules' \
-H "Content-type: application/json" \
-H "Authorization: Bearer $APP_ACCESS_TOKEN" -d \
'{
  "add": [
    {"value": "cat has:images", "tag": "gatti con immagini"}
  ]
}'`

Passo quattro: Autenticare la richiesta

Poiché gli endpoint delle regole del filtered stream richiedono OAuth 2.0 App-Only authentication, è necessario sostituire $APP_ACCESS_TOKEN nel comando cURL del passo tre con l’App Access Token che hai generato nei prerequisiti.

Passo cinque: Aggiungere la regola allo stream

Il passo successivo è eseguire la richiesta cURL, che aggiungerà la regola allo stream. Copia e incolla il comando cURL nell’interfaccia a riga di comando e premi Invio.

Se la richiesta cURL è andata a buon fine, riceverai una risposta contenente dati relativi a value, tag e id (che funge da identificatore univoco della regola). Questa risposta sarà simile alla seguente:

{
  "data": [
    {
      "value": "cat has:images",
      "tag": "gatti con immagini",
      "id": "1273026480692322304"
    }
  ],
  "meta": {
    "sent": "2020-06-16T22:55:39.356Z",
    "summary": {
      "created": 1,
      "not_created": 0,
      "valid": 1,
      "invalid": 0
    }
  }
}

Puoi verificare che la tua regola sia stata aggiunta correttamente inviando la seguente richiesta GET all’endpoint delle regole, assicurandoti ancora una volta di sostituire $APP_ACCESS_TOKEN con il tuo token. Questa richiesta restituirà l’elenco completo di tutte le regole aggiunte al tuo stream.

curl -X GET 'https://api.x.com/2/tweets/search/stream/rules' \
-H "Authorization: Bearer $APP_ACCESS_TOKEN"

Se la richiesta cURL è andata a buon fine, dovresti ricevere quanto segue:

{
	"data": [{
		"id": "1273028376882589696",
		"value": "cat has:images",
		"tag": "gatti con immagini"
	}],
	"meta": {
		"sent": "2020-06-16T23:14:06.498Z"
	}
}

Sesto passaggio: identifica e specifica quali fields desideri recuperare

Se ti connetti allo stream dopo il quinto passaggio, nella risposta riceverai i campi predefiniti dell’Oggetto Post: id, text ed edit_history_tweet_ids. Se desideri ricevere campi aggiuntivi oltre a questi, dovrai specificarli nella richiesta usando i parametri fields e/o expansions.

Per questo esercizio, richiederemo tre insiemi diversi di campi da oggetti differenti:

1. Il campo aggiuntivo tweet.created_at negli oggetti Post principali.
2. I campi predefiniti dell’oggetto utente degli autori associati per i Post restituiti: id, name e username
3. Il campo aggiuntivo user.created_at negli oggetti utente associati.  

Per richiedere questi campi, dovrai includere quanto segue nella richiesta:

Key	Value	Returned fields
tweet.fields	created_at	tweets.created_at
expansions	author_id	includes.users.id, includes.users.name, includes.users.username
user.fields	created_at	includes.users.created_at

Ora che lo sai, puoi comporre l’URL della richiesta per connetterti allo stream, che avrà questo aspetto:

https://api.x.com/2/tweets/search/stream?tweet.fields=created_at&expansions=author_id&user.fields=created_at

Settimo passaggio: connettiti allo stream e verifica la risposta

Ora che la tua regola è attiva e hai specificato quali fields vuoi ricevere, sei pronto a connetterti allo stream, che consegnerà Oggetti Post conformi alla regola inviata. Ecco come si presenta il comando cURL dopo aver aggiunto l’URL dal sesto passaggio alla tua richiesta:

curl -X GET -H "Authorization: Bearer $APP_ACCESS_TOKEN" "https://api.x.com/2/tweets/search/stream?tweet.fields=created_at&expansions=author_id&user.fields=created_at"

Ancora una volta, questa richiesta deve essere autenticata utilizzando OAuth 2.0 App-Only, quindi assicurati di sostituire $APP_ACCESS_TOKEN con le tue credenziali prima di copiarla e incollarla nel tuo strumento a riga di comando.

Una volta connesso al filtered stream, inizierai a ricevere Post che corrispondono alle tue regole nel seguente formato JSON:

{
  "data": [
    {
      "author_id": "2244994945",
      "created_at": "2022-09-14T19:00:55.000Z",
      "id": "1228393702244134912",
      "edit_history_tweet_ids": ["1228393702244134912"],
      "text": "Cosa ha scritto lo sviluppatore nel suo biglietto di San Valentino?\n  \nwhile(true) {\n    I = Love(You);  \n}"
    },
    {
      "author_id": "2244994945",
      "created_at": "2022-09-12T17:09:56.000Z",
      "id": "1227640996038684673",
       "edit_history_tweet_ids": ["1227640996038684673"],
      "text": "Dottori: Googlare cose online non ti rende un dottore\n\nSviluppatori: https://t.co/mrju5ypPkb"
    },
    {
      "author_id": "2244994945",
      "created_at": "2022-09-27T20:26:41.000Z",
      "id": "1199786642791452673",
      "edit_history_tweet_ids": ["1199786642791452673"],
      "text": "C#"
    }
  ],
  "includes": {
    "users": [
      {
        "created_at": "2013-12-14T04:35:55.000Z",
        "id": "2244994945",
        "name": "Twitter Dev",
        "username": "TwitterDev"
      }
    ]
  }
}

Se desideri chiudere la connessione, puoi premere Ctrl+C nel tuo strumento da riga di comando su macOS o Windows per interromperla, oppure chiudere la finestra.