Inicio rápido

​

Introducción a los endpoints de stream filtrado

Esta guía de inicio rápido te ayudará a realizar tu primera solicitud al grupo de endpoints de stream filtrado usando una solicitud cURL. cURL es una herramienta de línea de comandos que permite realizar solicitudes con una configuración mínima.

Si deseas ver código de ejemplo en diferentes lenguajes, visita nuestro repositorio de GitHub de X API v2 sample code.

Requisitos previos

Para completar esta guía, necesitarás un conjunto de claves y tokens para autenticar tu solicitud. Puedes generar estas claves y tokens siguiendo estos pasos:

• Regístrate para obtener una cuenta de desarrollador y recibe la aprobación.
• Crea un Proyecto y una App de desarrollador asociada en el Portal de desarrolladores.
• Ve a la página “Keys and tokens” de tu App para generar las credenciales necesarias. Asegúrate de guardar todas las credenciales en un lugar seguro.

​

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 mediante 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: Añade una etiqueta a tu regla

Puedes añadir varias reglas simultáneas a tu stream. Cuando abras tu conexión de streaming, los Posts que cumplan cualquiera de estas reglas pasarán por la misma conexión. Para identificar qué Post corresponde a cada regla, puedes incluir una etiqueta junto con la solicitud de creación de la regla. Cada Post que coincida con esa regla incluirá un campo tag dentro de la carga útil 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 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 queremos agregar esta regla al stream. Este cuerpo JSON tendrá el siguiente aspecto:

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

Ahora que has configurado por completo este cuerpo JSON, puedes añadirlo a una solicitud cURL, que tendrá el siguiente aspecto. Esta solicitud aún no está lista, así que espera a 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 autenticación 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 requisitos previos.

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 Intro.

Si tu solicitud cURL se realizó correctamente, recibirás una respuesta que contiene información sobre tu value, tag e id (sirve como identificador único para tu regla). Esta respuesta se verá similar a esto:

{
  "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
    }
  }
}

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

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

Si tu solicitud de 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: identifica y especifica qué fields deseas recuperar

Si te conectas al stream después del paso cinco, recibirás en tu respuesta los campos predeterminados del objeto 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 fields y/o expansions.

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

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

Para solicitar estos campos, deberás incluir 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 la URL de tu solicitud para conectarte al stream, que se verá así:

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, ya está listo para conectarse al stream, que entregará objetos Post que coincidan con la regla que envió. Así 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 mediante 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, empezarás a recibir Posts que cumplan 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: Buscar en Google no te hace médico\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 deseas cerrar la conexión, puedes pulsar Control‑C en tu herramienta de línea de comandos, tanto en Mac como en Windows, para interrumpirla; también puedes cerrar la ventana.