Saltar al contenido principal

​
Crear un cliente para consumir datos de streaming

Al usar un endpoint de streaming, conviene seguir algunas prácticas recomendadas generales para optimizar su uso.    

​
Diseño del cliente

Al crear una solución con el endpoint de flujo filtrado, necesitará un cliente que pueda hacer lo siguiente:
  1. Establecer una conexión de streaming HTTPS con el endpoint de flujo filtrado.
  2. Enviar solicitudes POST de forma asíncrona al endpoint de reglas del flujo filtrado para agregar y eliminar reglas del flujo.
  3. Gestionar volúmenes bajos de datos: mantener la conexión de streaming, detectando objetos Post y señales de keep-alive.
  4. Gestionar volúmenes altos de datos: desacoplar la ingestión del flujo del procesamiento adicional mediante procesos asíncronos y asegurarse de vaciar regularmente los búferes del lado del cliente.
  5. Administrar el seguimiento del consumo de volumen en el lado del cliente.
  6. Detectar desconexiones del flujo, evaluar y reconectarse al flujo automáticamente.  

​
Conectarse a un endpoint de streaming

Establecer una conexión con los endpoints de streaming de X API v2 implica realizar una solicitud HTTP de muy larga duración y procesar la respuesta de forma incremental. Conceptualmente, puede pensarlo como descargar un archivo infinitamente largo a través de HTTP. Una vez establecida la conexión, el servidor de X entregará eventos de Post a través de la conexión mientras esta permanezca abierta.  

​
Consumo de data

Tenga en cuenta que los campos individuales de los objetos JSON no tienen un orden fijo y que no todos los campos estarán presentes en todas las circunstancias. Del mismo modo, las actividades por separado no se entregan en orden y pueden aparecer mensajes duplicados. Tenga presente que, con el tiempo, pueden agregarse nuevos tipos de mensajes y enviarse a través del stream. Por lo tanto, su cliente debe tolerar:
  • Campos en cualquier orden
  • Campos inesperados o ausentes
  • Posts sin orden
  • Mensajes duplicados
  • Nuevos tipos de mensajes arbitrarios que lleguen por el stream en cualquier momento
Además de los datos relevantes del Post y los parámetros de fields solicitados, en una conexión de stream pueden entregarse los siguientes tipos de mensajes. Tenga en cuenta que esta lista puede no ser exhaustiva: pueden incorporarse objetos adicionales en los streams. Asegúrese de que su analizador tolere formatos de mensaje inesperados.  

​
Almacenamiento en búfer 

Los endpoints de streaming enviarán datos tan pronto como estén disponibles, lo que puede generar volúmenes altos en muchos casos. Si el servidor de X no puede escribir nuevos datos en el stream de inmediato (por ejemplo, si tu cliente no está leyendo lo suficientemente rápido; consulta manejo de desconexiones para más información), almacenará el contenido en un búfer de su lado para permitir que tu cliente se ponga al día. Sin embargo, cuando ese búfer se llena, se inicia una desconexión forzada para cerrar la conexión, y los Posts almacenados en el búfer se descartarán y no se reenviarán. Consulta a continuación para más detalles. Una manera de identificar cuándo tu App se está quedando atrás es comparar la marca de tiempo de los Posts que se reciben con la hora actual y hacer seguimiento de esto a lo largo del tiempo. Aunque los atascos del stream no pueden eliminarse por completo debido a la posible latencia e interrupciones en la internet pública, pueden reducirse en gran medida mediante una configuración adecuada de tu App. Para minimizar su ocurrencia:
  • Asegúrate de que tu cliente lea el stream lo suficientemente rápido. Por lo general, no deberías realizar procesamiento real mientras lees el stream. Lee el stream y deriva la actividad a otro hilo/proceso/almacén de datos para procesarla de forma asíncrona.
  • Asegúrate de que tu centro de datos tenga ancho de banda de entrada suficiente para admitir grandes volúmenes de datos sostenidos, así como picos significativamente mayores (por ejemplo, 5-10x el volumen normal). En el caso del filtered stream, el volumen y el ancho de banda correspondiente requeridos de tu lado dependen por completo de qué Posts estén coincidiendo con tus reglas.  

​
Seguimiento del uso y gestión de reglas

Dado que las expectativas de los desarrolladores sobre cuál debería ser un volumen de datos “normal” para sus streams varían, no tenemos una recomendación general para un porcentaje específico de disminución/aumento ni para un período de tiempo. Considere supervisar los volúmenes de datos de su stream para detectar desviaciones inesperadas. Una disminución del volumen de datos puede ser sintomática de un problema distinto a una desconexión del stream. En tal situación, un stream seguiría recibiendo la señal de keep-alive y probablemente algunos datos de actividad nuevos. Sin embargo, un número significativamente menor de Posts debería llevarle a investigar si hay algo que esté causando la disminución del volumen de datos entrante a su aplicación o red; consulte la página de estado para cualquier aviso relacionado. Para implementar este tipo de monitoreo, podría rastrear la cantidad de Posts nuevos que espera ver en un período de tiempo determinado. Si el volumen de datos de un stream cae lo suficientemente por debajo del umbral especificado y no se recupera dentro de un período establecido, entonces se deberían iniciar alertas y notificaciones. También puede que quiera supervisar un gran aumento en el volumen de datos, particularmente si está en proceso de modificar reglas en un stream filtrado, o si ocurre un evento que produzca un pico en la actividad de Posts. Es importante tener en cuenta que los Posts entregados a través de un stream filtrado sí cuentan para el volumen mensual total de Posts, y debería rastrear y ajustar el consumo para optimizar. Si el volumen es alto, considere agregar el operador sample: a cada una de sus reglas para reducir de una coincidencia del 100% a sample:50 o sample:25 cuando sea necesario. Además, le recomendamos implementar medidas dentro de su App que alerten a su equipo si el volumen supera un umbral preestablecido, y posiblemente introducir otras medidas como la eliminación automatizada de reglas que estén trayendo demasiados datos, o desconectarse del stream por completo en circunstancias extremas.  

​
Responder a los mensajes del sistema

Señales de keep-alive Al menos cada 20 segundos, el stream enviará una señal de keep-alive (o heartbeat) en forma de un retorno de carro \r\n a través de la conexión abierta para evitar que su cliente agote el tiempo de espera. Su aplicación cliente debe tolerar los caracteres \r\n en el stream. Si su cliente implementa correctamente un tiempo de espera de lectura en su biblioteca HTTP, su App podrá apoyarse en el protocolo HTTP y en su biblioteca HTTP para generar un evento si no se lee data dentro de ese período, y no necesitará supervisar explícitamente el carácter \r\n. Este evento normalmente será una excepción generada u otro tipo de evento, según la biblioteca HTTP utilizada. Se recomienda encarecidamente envolver sus métodos HTTP con controladores de errores/eventos para detectar estos timeouts. En caso de timeout, su aplicación debe intentar reconectarse. Mensajes de error Los endpoints de streaming de v2 también pueden entregar mensajes de error en el stream. A continuación se muestra el formato básico de estos mensajes, junto con algunos ejemplos. Tenga en cuenta que los mensajes entregados podrían cambiar, introduciéndose nuevos mensajes. Las aplicaciones cliente deben tolerar cargas útiles de mensajes del sistema que cambian con el tiempo. Tenga en cuenta que los mensajes de error incluirán enlaces a la documentación que describe cómo resolver el problema. Formato del mensaje: 
	"errors": [{
		"title": "operational-disconnect",
		"disconnect_type": "UpstreamOperationalDisconnect",
		"detail": "Este flujo se ha desconectado en el origen por motivos operativos.",
		"type": "https://api.x.com/2/problems/operational-disconnect"
	}]
}
Tenga en cuenta que los mensajes de error que indican una desconexión forzada por un búfer lleno pueden no llegar nunca a su cliente si el cuello de botella que provocó la desconexión forzada impide que se transmitan. En consecuencia, su App no debe depender de estos mensajes para iniciar una reconexión.