Guía rápida

​

Introducción a los endpoints de stream filtrado

Esta Guía rápida le ayudará a realizar su primera solicitud al grupo de endpoints de stream filtrado utilizando una solicitud cURL. cURL es una herramienta de línea de comandos que le permite realizar solicitudes con una configuración mínima.

Si desea ver Código de muestra en diferentes lenguajes, visite nuestro repositorio de GitHub X API v2 sample code. 

Requisitos previos

Para completar esta guía, necesitará contar con un conjunto de keys and tokens para autenticar su solicitud. Puede generar estas keys and tokens siguiendo estos pasos:

• Regístrese para obtener una cuenta de desarrollador y reciba la aprobación.
• Cree un Project y una App de desarrollador asociada en el portal de desarrolladores.
• Vaya a la página “Keys and tokens” de su App para generar las credenciales requeridas. Asegúrese de guardar todas las credenciales en una ubicación segura.

​

Pasos para crear una solicitud de stream filtrado con cURL

Paso uno: crear una regla

Las reglas se componen de uno o varios operadores que se combinan usando lógica booleana y paréntesis para definir qué Posts se entregarán a tu stream. En esta guía, filtraremos el stream para encontrar Posts que contengan tanto la palabra clave “cat” como imágenes. Esta es nuestra regla:

has:images

Paso dos: agrega una etiqueta a tu regla

Puedes agregar varias reglas concurrentes a tu stream. Cuando abras tu conexión de streaming, los Posts que coincidan con cualquiera de estas reglas fluirán por la misma conexión de streaming. Para saber qué Post coincide con cada regla, puedes incluir una etiqueta junto con tu solicitud de creación de regla. Cada Post que coincida con esa regla incluirá un campo tag dentro del payload del Post indicando con qué regla coincidió. Para esta regla, vamos a asignar la siguiente etiqueta:

with images

Paso tres: Agrega tu regla al stream

Este endpoint requiere que envíes un cuerpo con tipo application/JSON junto con esta solicitud que contenga tu regla y su etiqueta. También notarás que hemos incluido el valor de la regla y la etiqueta dentro de un objeto add, ya que estamos intentando agregar esta regla al stream. Este cuerpo JSON se verá así:

{
  "add": [
    {
      "value": "cat has:images",
      "tag": "gatos con imágenes"
    }
  ]
}

Ahora que has configurado completamente este cuerpo JSON, puedes agregarlo a una solicitud cURL, que tendrá el siguiente aspecto. Esta solicitud aún no está lista, así que espera para enviarla hasta un paso posterior.

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": "gatos con imágenes"}
  ]
}'`

Paso cuatro: Autentica tu solicitud

Dado que los endpoints de reglas del stream filtrado requieren OAuth 2.0 App-Only, deberás reemplazar $APP_ACCESS_TOKEN en el comando cURL del paso tres por el App Access Token que generaste en los prerrequisitos.

Paso cinco: Agrega tu regla al stream

El siguiente paso es ejecutar tu solicitud cURL, lo que agregará la regla a tu stream. Copia y pega el comando cURL en tu interfaz de línea de comandos y presiona “Return”.

Si tu solicitud cURL se ejecutó correctamente, recibirás una respuesta que contiene data sobre tu value, tag e id (que funciona como identificador único de tu regla). Esta respuesta se verá similar a lo siguiente:

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

Puede verificar que su regla se haya agregado correctamente enviando la siguiente solicitud GET al endpoint de reglas, asegurándose nuevamente de reemplazar $APP_ACCESS_TOKEN por su token. Esta solicitud devolverá una lista completa de todas las reglas que se han agregado a su stream.

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

Si la solicitud cURL se realizó correctamente, deberías recibir lo siguiente:

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

Paso seis: identifique y especifique qué fields desea obtener

Si te conectas al stream después del paso cinco, recibirás en tu respuesta los campos predeterminados del Objeto de Post: id, text y edit_history_tweet_ids. Si deseas recibir campos adicionales más allá de estos, tendrás que especificarlos en tu solicitud con los parámetros field y/o expansion.

Para este ejercicio, solicitaremos tres conjuntos diferentes de campos de distintos objetos:

1. El campo adicional tweet.created_at en los objetos de Post principales.
2. Los campos predeterminados del objeto de usuario de los autores asociados para los Posts devueltos: id, name y username
3. El campo adicional user.created_at en los objetos de usuario asociados.  

Para solicitar estos campos, deberás pasar lo siguiente en tu solicitud:

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

Ahora que sabes esto, puedes armar tu URL de solicitud para conectarte al stream, que tendrá el siguiente aspecto:

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

Paso siete: Conéctese al stream y revise su respuesta

Ahora que su regla está configurada y ha especificado qué fields desea que se devuelvan, está listo para conectarse al stream, que entregará Objeto de Post que coincidan con la regla que envió. Así es como se ve el comando cURL una vez que agregó la URL del paso seis a su solicitud:

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"

Una vez más, esta solicitud debe autenticarse con OAuth 2.0 App-Only, así que asegúrate de reemplazar $APP_ACCESS_TOKEN por tus credenciales antes de copiarla y pegarla en tu herramienta de línea de comandos.

Una vez que te conectes al stream filtrado, comenzarás a recibir Posts que coincidan con tus reglas en el siguiente formato JSON:

{
  "data": [
    {
      "author_id": "2244994945",
      "created_at": "2022-09-14T19:00:55.000Z",
      "id": "1228393702244134912",
      "edit_history_tweet_ids": ["1228393702244134912"],
      "text": "¿Qué escribió el desarrollador en su tarjeta de San Valentín?\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": "Doctores: Googlear cosas en línea no te convierte en doctor\n\nDesarrolladores: 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"
      }
    ]
  }
}

Si desea cerrar la conexión, puede presionar Control+C en su herramienta de línea de comandos en sistemas Mac o Windows para interrumpirla, o bien cerrar la ventana.