Saltar al contenido principal

​
Creación de reglas para el stream filtrado

Los endpoints de stream filtrado entregan Posts que cumplen un conjunto de reglas aplicadas al stream. Las reglas se componen de operadores que se usan para hacer coincidir una variedad de atributos de los Posts. Puedes aplicar varias reglas a un stream mediante el endpoint POST /tweets/search/stream/rules. Una vez que agregues reglas y te conectes a tu stream mediante el endpoint GET /tweets/search/stream, solo se entregarán, a través de una conexión de streaming persistente, los Posts que coincidan con tus reglas. No necesitas desconectarte de tu stream para agregar o eliminar reglas. 

​
Tabla de contenidos

​
Crear una regla

​
Limitaciones de las reglas

Los límites en la cantidad de reglas dependerán del nivel de acceso aplicado a tu Project. Puedes ver cómo se aplican estos límites en la página de introducción a la transmisión filtrada.

​
Tipos de operadores: autónomos y se requiere una conjunción

Los operadores autónomos pueden usarse solos o junto con cualquier otro operador (incluidos aquellos que requieren conjunción). Por ejemplo, la siguiente regla funcionará porque utiliza el operador #hashtag, que es autónomo: #xapiv2 Los operadores se requiere una conjunción no pueden usarse por sí solos en una regla; solo pueden usarse cuando se incluye al menos un operador autónomo en la regla. Esto se debe a que usar estos operadores solos sería demasiado general y haría coincidir un volumen extremadamente alto de Posts. Por ejemplo, las siguientes reglas no son compatibles, ya que contienen únicamente operadores que requieren conjunción: has:media has:links OR is:retweet Si agregamos un operador autónomo, como la frase “X data”, la regla funcionaría correctamente. “X data” has:mentions (has:media OR has:links)

​
Operadores booleanos y agrupación

Si deseas encadenar varios operadores en una sola regla, tienes las siguientes herramientas a tu disposición:
Lógica ANDLos operadores sucesivos con un espacio entre ellos aplican la lógica booleana “AND”, lo que significa que los Posts coincidirán solo si se cumplen ambas condiciones. Por ejemplo, snow day #NoSchool coincidirá con Posts que contengan los términos snow y day y el hashtag #NoSchool.
Lógica ORLos operadores sucesivos con OR entre ellos aplican la lógica OR, lo que significa que los Posts coincidirán si se cumple cualquiera de las condiciones. Por ejemplo, usar grumpy OR cat OR #meme coincidirá con cualquier Post que contenga al menos los términos grumpy o cat, o el hashtag #meme.
Lógica NOT, negaciónAntepon un guion (-) a una palabra clave (o a cualquier operador) para negarla (NOT). Por ejemplo, cat #meme -grumpy coincidirá con Posts que contengan el hashtag #meme y el término cat, pero solo si no contienen el término grumpy. Una cláusula de regla común es -is:retweet, que no coincidirá con Retweets y, por tanto, coincidirá solo con Posts originales, Quote Tweets y respuestas. Todos los operadores se pueden negar, pero los operadores negados no se pueden usar solos.
AgrupaciónPuedes usar paréntesis para agrupar operadores. Por ejemplo, (grumpy cat) OR (#meme has:images) devolverá Posts que contengan los términos grumpy y cat, o Posts con imágenes que contengan el hashtag #meme. Ten en cuenta que primero se aplican los AND y luego los OR.
Una nota sobre las negacionesTodos los operadores se pueden negar excepto sample:, y -is:nullcast siempre debe estar negado. Los operadores negados no se pueden usar solos.No niegues un conjunto de operadores agrupados entre paréntesis. En su lugar, niega cada operador individual.Por ejemplo, en lugar de usar skiing -(snow OR day OR noschool), te sugerimos usar skiing -snow -day -noschool.

​
Orden de operaciones

Al combinar la funcionalidad AND y OR, el siguiente orden de operaciones determinará cómo se evalúa tu regla.
  1. Primero se combinan los operadores conectados por la lógica AND
  2. Luego se aplican los operadores conectados con la lógica OR
Por ejemplo:
  • apple OR iphone ipad se evaluará como apple OR (iphone ipad)
  • ipad iphone OR android se evaluará como (iphone ipad) OR android
Para eliminar dudas y asegurarte de que tu regla se evalúe como pretendes, agrupa los términos con paréntesis cuando corresponda. Por ejemplo:
  • (apple OR iphone) ipad
  • iphone (ipad OR android)

​
Puntuación, diacríticos y distinción entre mayúsculas y minúsculas

Si especificas una regla de palabra clave o hashtag con acentos o diacríticos, coincidirá con Posts que contengan la palabra exacta con los acentos o diacríticos correspondientes, pero no con aquellas que tengan las letras correctas, pero sin el acento o diacrítico. Por ejemplo, las reglas con la palabra clave diacrítica o el hashtag #cumpleaños coincidirán con Posts que contengan diacrítica o #cumpleaños porque incluyen el acento o diacrítico. Sin embargo, estas reglas no coincidirán con Posts que contengan Diacritica o #cumpleanos sin la tilde en í o la eñe. Los caracteres con acentos o diacríticos se tratan igual que los caracteres normales y no se consideran límites de palabra. Por ejemplo, una regla con la palabra clave cumpleaños solo coincidiría con Posts que contengan la palabra cumpleaños y no coincidiría con Posts que contengan cumplea, cumplean u os. Todos los operadores se evalúan sin distinguir entre mayúsculas y minúsculas. Por ejemplo, la regla cat coincidirá con todo lo siguiente: cat, CAT, Cat.
El comportamiento de coincidencia de Search Posts difiere del de filtered stream. Al crear una consulta de Search Posts, ten en cuenta que las palabras clave y los hashtags que incluyen acentos o diacríticos coincidirán tanto con el término con acentos y diacríticos como con caracteres normales.Por ejemplo, las consultas de Search Posts que incluyan la palabra clave Diacrítica o el hashtag #cumpleaños coincidirán tanto con Diacrítica y #cumpleaños como también con Diacritica o #cumpleanos sin la tilde en í o la eñe.

​
Especificidad y eficiencia

Cuando empiece a crear su regla, es importante tener en cuenta algunos aspectos.
  • Usar operadores amplios y autónomos para su regla, como una sola palabra clave o un #hashtag, generalmente no se recomienda, ya que probablemente hará coincidir un volumen masivo de Posts. Crear una regla más sólida dará como resultado un conjunto más específico de Posts coincidentes y, con suerte, reducirá la cantidad de ruido en la carga útil que tendrá que cribar para encontrar información valiosa.
    • Por ejemplo, si su regla fuera solo la palabra clave happy, probablemente obtendría entre 200.000 y 300.000 Posts por día.
    • Agregar más operadores condicionales reduce sus resultados de búsqueda; por ejemplo, (happy OR happiness) place_country:GB -birthday -is:retweet
  • Escribir reglas eficientes también ayuda a mantenerse dentro de la restricción de longitud de caracteres de la regla. El recuento de caracteres incluye toda la cadena de la regla, incluidos los espacios y los operadores.
    • Por ejemplo, la siguiente regla tiene 59 caracteres: (happy OR happiness) place_country:GB -birthday -is:retweet

​
Comportamiento de coincidencia en los Quote Tweets

Al usar los endpoints de flujo filtrado, los operadores harán coincidencia tanto con el contenido del Post original citado como con el contenido incluido en el Quote Tweet. Sin embargo, ten en cuenta que los endpoints de Search Posts no harán coincidencia con el contenido del Post original citado, pero sí coincidirán con el contenido del Quote Tweet.

​
Crear una regla de forma iterativa

Prueba tu regla temprano y con frecuencia
Es poco común que una regla arroje los resultados “correctos” a la primera. Hay tanto contenido en X que puede o no ser evidente al principio, y la sintaxis de reglas descrita arriba puede resultar difícil de ajustar a tu búsqueda. A medida que creas una regla, es importante probarla periódicamente con el endpoint de streaming para ver qué data devuelve. También puedes probar con uno de los endpoints de Search Post, siempre que los operadores que estés usando también estén disponibles en ese endpoint. Para esta sección, comenzaremos con la siguiente regla y la ajustaremos según los resultados que obtengamos durante la prueba: happy OR happiness
Usa los resultados para acotar la regla
A medida que pruebas la regla, debes revisar los Posts devueltos para comprobar si incluyen los datos que esperas y deseas recibir. Comenzar con una regla amplia y un superconjunto de coincidencias de Post te permite revisar el resultado y acotar la regla para filtrar los resultados no deseados.   Cuando probamos la regla de ejemplo, observamos que estábamos recibiendo Posts en varios idiomas. En esta situación, queremos recibir únicamente Posts en inglés, así que vamos a añadir el operador lang:: (happy OR happiness) lang:en La prueba devolvió varios Posts felicitando cumpleaños, así que vamos a añadir -birthday como operador de palabra clave negada. También queremos recibir únicamente Posts originales, por lo que añadimos el operador negado -is:retweet: (happy OR happiness) lang:en -birthday -is:retweet
Ajustar para incluir cuando sea necesario
Si notas que no estás recibiendo los datos que esperas y sabes que hay Posts existentes que deberían devolverse, quizá necesites ampliar tu regla eliminando operadores que podrían estar filtrando los datos deseados. En nuestro ejemplo, notamos que había otros Posts en nuestra línea de tiempo personal que expresaban la emoción que buscamos y no se incluyeron en los resultados de la prueba. Para asegurar una mayor cobertura, vamos a añadir las palabras clave excited y elated. (happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet Las tendencias en X cambian rápidamente. Mantener su regla debe ser un proceso activo. Si planea usar una sola regla por un tiempo, le sugerimos revisar periódicamente los datos que está recibiendo para ver si necesita hacer ajustes. En nuestro ejemplo, notamos que empezamos a recibir algunos Posts que deseaban a las personas “felices fiestas”. Como no queremos que esos Posts se incluyan en nuestros resultados, vamos a agregar la palabra clave negada -holidays. (happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays

​
Agregar y eliminar reglas

Usarás el endpoint POST /2/tweets/search/stream/rules tanto para agregar como para eliminar reglas de tu flujo. Para agregar una o más reglas a tu flujo, envía un cuerpo JSON add con un arreglo que contenga el parámetro value con la regla, y el parámetro opcional tag con texto libre que puedes usar para identificar qué Posts devueltos coinciden con esta regla. Por ejemplo, si quisieras agregar un conjunto de reglas a tu flujo, tu comando cURL podría verse así: 
curl -X POST 'https://api.x.com/2/tweets/search/stream/rules' \
-H "Content-type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" -d \
'{
  "add": [
    {"value": "cat has:media", "tag": "gatos con multimedia"},
    {"value": "cat has:media -grumpy", "tag": "gatos felices con multimedia"},
    {"value": "meme", "tag": "cosas divertidas"},
    {"value": "meme has:images"}
  ]
}'
De manera similar, para eliminar una o más reglas de tu flujo, envía un cuerpo JSON delete con el arreglo que contiene el parámetro id, incluyendo los id de las reglas que deseas eliminar. Por ejemplo, si quisieras eliminar un conjunto de reglas de tu flujo, tu comando cURL podría verse así: 
curl -X POST 'https://api.x.com/2/tweets/search/stream/rules' \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -d \
  '{
    "delete": {
      "ids": [
        "1165037377523306498",
        "1165037377523306499"
      ]
    }
  }'
Tenemos código de ejemplo en distintos lenguajes disponible en nuestro GitHub.

​
Ejemplos de reglas

Seguimiento de un desastre natural
La siguiente regla coincidió con Posts provenientes de agencias meteorológicas y estaciones que hablaban del huracán Harvey, que azotó Houston en 2017. Observa el uso de la etiqueta matching rules y el formato JSON que deberás usar al enviar la regla al endpoint POST /2/tweets/search/stream/rules. 
{
    "value": "-is:retweet has:geo (from:NWSNHC OR from:NHC_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1)",
    "tag": "theme:info has:geo original de agencias meteorológicas y estaciones de medición"
}
Revisar el sentimiento de una conversación
La siguiente regla puede utilizarse para comprender mejor el sentimiento de la conversación que se desarrolla en torno al hashtag #nowplaying, pero solo a partir de Posts publicados en Norteamérica. 
{
    "value": "#nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place_country:US OR place_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing",
    "tag": "#nowplaying positivo"
},
{
    "value": "#nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place_country:US OR place_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible",
    "tag": "#nowplaying negativo"
}
Encontrar Posts relacionados con una anotación de Post específica
Esta regla se creó para buscar Posts originales que incluyan una imagen de una mascota que no sea un gato y cuyo idioma identificado en el Post sea japonés. Para ello, usamos el operador context: para aprovechar la funcionalidad de anotaciones de Post. Primero usamos el endpoint de Post lookup y el parámetro de fields tweet.fields=context_annotations para identificar qué IDs de domain.entity debemos usar en nuestra consulta:
  • Los Posts relacionados con gatos devuelven domain 66 (categoría Interests and Hobbies) con entity 852262932607926273 (Cats).
  • Los Posts relacionados con mascotas devuelven domain 65 (Interests and Hobbies Vertical) con entity 852262932607926273 (Pets).  
Así se vería la regla: 
{
    "value": "context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja",
    "tag": "Mascotas japonesas con imágenes - sin gatos"
}