Saltar al contenido principal

​
Cómo integrarte con los endpoints de Timelines

Esta página contiene información sobre varias herramientas y conceptos clave que debes conocer a medida que integras los endpoints de Timelines en tu sistema. Hemos dividido la página en las siguientes secciones:

​
Herramientas útiles

Antes de explorar algunos conceptos clave, te recomendamos usar una de las siguientes herramientas o ejemplos de código para empezar a probar la funcionalidad de estos endpoints. Ejemplos de código ¿Quieres configurar estos endpoints con código en tu lenguaje de programación preferido? Tenemos varios ejemplos de código disponibles que puedes usar como punto de partida en nuestra página de GitHub. Bibliotecas Aprovecha una de nuestras bibliotecas de terceros de la comunidad para comenzar. Puedes encontrar una biblioteca compatible con los endpoints v2 buscando la etiqueta de versión correspondiente. Postman Postman es una excelente herramienta para probar estos endpoints. Cada solicitud de Postman incluye todos los parámetros de ruta y de cuerpo para ayudarte a entender rápidamente qué tienes disponible. Para obtener más información sobre nuestras colecciones de Postman, visita nuestra página Uso de Postman.

​
Conceptos clave

Autenticación Todos los endpoints de X API v2 requieren que las solicitudes estén autenticadas con un conjunto de credenciales, también conocidas como claves y tokens. Puedes usar Contexto de usuario de OAuth 1.0a o Código de autorización de OAuth 2.0 con PKCE para autenticar solicitudes a estos endpoints. Puedes usar OAuth 2.0 App-Only para el timeline de Posts de usuario y el timeline de menciones de usuario. Contexto de usuario de OAuth 1.0a requiere que utilices tus API Keys, user Access Tokens y algunos otros parámetros para crear un encabezado de autorización, que luego incluirás en tu solicitud. Los Access Tokens deben estar asociados con el usuario en cuyo nombre realizas la solicitud. Si deseas generar un conjunto de Access Tokens para otro usuario, ese usuario debe autorizar tu App utilizando el flujo OAuth de 3 patas. Ten en cuenta que OAuth 1.0a puede ser difícil de usar. Si no estás familiarizado con este método de autenticación, te recomendamos usar una biblioteca, una herramienta como Postman o OAuth 2.0 para autenticar tus solicitudes. Si deseas solicitar un Post o métricas privadas desde estos endpoints, tendrás que usar Contexto de usuario de OAuth 1.0a o Código de autorización de OAuth 2.0 con PKCE, lo que garantizará que cuentes con los permisos adecuados del usuario propietario de ese contenido. OAuth 2.0 App-Only solo requiere que incluyas un OAuth 2.0 App Access Token en tu solicitud. Puedes generar un App Access Token directamente en una App de desarrollador o generarlo usando el endpoint POST oauth2/token. Puedes usar esto para el timeline de Posts de usuario o el timeline de menciones de usuario. Código de autorización de OAuth 2.0 con PKCE permite un mayor control sobre el alcance de una aplicación y flujos de autorización en múltiples dispositivos. OAuth 2.0 te permite elegir scopes específicos y granulares que te otorgan permisos concretos en nombre de un usuario. Para habilitar OAuth 2.0 en tu App, debes activarlo en la configuración de autenticación de tu App, disponible en la sección de configuración de la App del Portal de desarrolladores.
Ten en cuentaSi solicitas los siguientes fields, se requiere Contexto de usuario de OAuth 1.0a o Código de autorización de OAuth 2.0:
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
Portal de desarrolladores, Proyectos y Apps de desarrollador Para trabajar con cualquier endpoint de X API v2, debes registrarte para obtener una cuenta de desarrollador, configurar un Project dentro de esa cuenta y crear una developer App dentro de ese Project. Tus claves y tokens dentro de esa developer App funcionarán para estos endpoints de timelines. Límites de frecuencia Cada día, muchos miles de desarrolladores realizan solicitudes a la X API. Para ayudar a gestionar el volumen, se aplican límites de frecuencia a cada endpoint que restringen el número de solicitudes que cada desarrollador puede realizar en nombre de una App o de un usuario autenticado. Se aplican diferentes límites de frecuencia a estos endpoints según el método de autenticación utilizado. Los límites de frecuencia a nivel de App se aplican a una App que realiza solicitudes usando OAuth 2.0 App-Only, mientras que el límite de frecuencia a nivel de usuario se aplica a solicitudes realizadas en nombre del usuario específico que autoriza usando Contexto de usuario de OAuth 1.0a. Estos dos límites se basan en la frecuencia de solicitudes dentro de una ventana de 15 minutos. Por ejemplo, una App que use autenticación OAuth 2.0 App-Only para ambos endpoints de cronologías puede hacer 1500 solicitudes (incluidas las de paginación) a la cronología de Posts del usuario y 450 solicitudes (incluidas las de paginación) a la cronología de menciones del usuario dentro de un período de 15 minutos. Esa misma App, dentro del mismo período de 15 minutos, con dos usuarios autorizados diferentes (usando Contexto de usuario de OAuth 1.0a) puede hacer 900 solicitudes (incluidas las de paginación) a la cronología de Posts del usuario y 180 solicitudes (incluidas las de paginación) a la cronología de menciones del usuario por cada usuario autenticado. La cronología de inicio en orden cronológico inverso tiene un límite por usuario de 180 solicitudes por ventana de 15 minutos. Con este endpoint puedes obtener todos los Posts creados en una cronología durante los últimos 7 días, así como los 800 más recientes independientemente de la fecha de creación. Fields and expansions X API v2 te permite seleccionar exactamente qué data quieres que se devuelva desde la API usando fields y expansions. El parámetro expansions te permite expandir objetos referenciados en el payload. Por ejemplo, este endpoint te permite solicitar objetos de encuestas, lugares, medios y otros usando el parámetro expansions. El parámetro fields te permite seleccionar exactamente qué fields dentro de los distintos objetos de data te gustaría recibir. De forma predeterminada, el objeto principal Post devuelto por estos endpoints incluye los fields id y text. Para recibir fields adicionales como author_id o public_metrics, tendrás que solicitarlos específicamente usando los parámetros fields. Algunos fields importantes que podrías considerar usar en tu integración son nuestros datos de encuestas, metrics, Post annotations y los fields de conversation ID. Hemos añadido una guía sobre cómo usar fields y expansions juntos en nuestro diccionario de datos de X API v2. Métricas de Post Los endpoints de X API v2 te permiten solicitar métricas de Post directamente desde el objeto Post devuelto, siempre que incluyas los fields adecuados en tu solicitud. Existen algunas limitaciones con las métricas de Post de las que deberías estar al tanto, específicamente relacionadas con la privacidad del usuario y los siguientes fields de respuesta:
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
Los fields señalados incluyen datos de métricas privadas, lo que significa que debes estar autorizado por el editor del Post para recuperar esta data en su nombre cuando uses el endpoint de la cronología de Posts del usuario; es decir, debes usar OAuth 1.0a User Context o OAuth 2.0 Authorization Code Flow with PKCE. Por ejemplo, para recibir non_public_metrics para la cronología de Posts del usuario con id 1234, tendrás que incluir en tu solicitud los tokens de acceso asociados con ese usuario. Puedes hacer que los usuarios autoricen tu App y recibir un conjunto de tokens de acceso asociados a ellos usando el flujo de OAuth de 3 pasos. Si estás usando la cronología de menciones del usuario, los fields señalados no estarán disponibles a menos que el autor que menciona haya autorizado tu App a acceder a sus datos de métricas privadas y estés usando los tokens de acceso de ese usuario al hacer la solicitud con Contexto de usuario de OAuth 1.0a. Todas las non_public_metrics, organic_metrics y promoted_metrics solo están disponibles para Posts creados en los últimos 30 días. Esto significa que, cuando solicites los fields señalados, los resultados se ajustarán automáticamente para incluir únicamente Posts de los últimos 30 días. Si se solicitan estos fields señalados, solo se devolverán los Posts cuyo autor sea el usuario autenticado; todos los demás Posts devolverán un mensaje de error. Paginación Estos endpoints utilizan paginación para que las respuestas se devuelvan rápidamente. En los casos en que haya más resultados de los que pueden enviarse en una sola respuesta (hasta 100 Posts para los endpoints de cronologías), tendrás que paginar. Usa el parámetro max_results para indicar cuántos resultados se devolverán por página y el parámetro pagination_token para obtener la siguiente página de resultados. Puedes obtener más información consultando nuestra guía de paginación. Filtrado de resultados Estos endpoints incluyen varios parámetros que puedes usar para filtrar los resultados. Con start_date y end_date, puedes acotar los resultados a un periodo de tiempo específico. Si prefieres usar IDs de Post para seleccionar un conjunto específico de Posts, puedes usar since_id y until_id. La cronología de Posts de usuario también tiene un parámetro exclude que puede quitar Retweets y respuestas de tus resultados.  Límites de Posts y volumen de Posts devueltos Los endpoints de cronología de Posts de usuario y de menciones de usuario están limitados en la cantidad de Posts que pueden devolver en un mes determinado. El endpoint de la cronología de inicio en orden cronológico inverso no está sujeto a esta limitación. Independientemente del endpoint de cronologías que uses, los Posts devueltos contarán para los límites de Posts a nivel de Proyecto. El uso se muestra en el Portal de desarrolladores, y el “mes” comienza en el día de renovación de tu suscripción que se muestra en el panel del Portal de desarrolladores.  El endpoint de la cronología de Posts de usuario solo devolverá los 3200 Posts más recientes publicados en la cronología de un usuario. Si configuras start_time y end_time en un periodo que incluye Posts más allá de los 3200 más recientes, recibirás una respuesta correcta, pero sin Posts. También es importante tener en cuenta que, si pasas excludes=replies con tus solicitudes a la cronología de Posts de usuario, solo se devolverán los 800 Posts más recientes. El endpoint de la cronología de menciones de usuario solo devolverá las 800 menciones de Post más recientes. El endpoint de la cronología de inicio en orden cronológico inverso devuelve los últimos 3200 Posts. Ediciones de Posts Los Posts que sean aptos para edición pueden editarse hasta cinco veces en los 30 minutos posteriores a la publicación del Post original. Los endpoints de búsqueda siempre proporcionarán la versión más reciente del Post. Si solo solicitas Posts que se publicaron hace 30 minutos o más, siempre recibirás la versión final del Post. Sin embargo, si tienes un caso de uso casi en tiempo real y estás consultando Posts publicados en los últimos treinta minutos, esos Posts podrían haberse editado después de que los recibieras. Estos Posts se pueden rehidratar con la búsqueda o el endpoint de Post Lookup para confirmar su estado final. Para obtener más información sobre cómo funcionan las ediciones de Posts, consulta la página Fundamentos de edición de Posts.   Casos límite
  • Al solicitar métricas no públicas en el endpoint de la cronología de Posts de usuario para Posts con más de 30 días, puedes ver un next_token en la respuesta con un recuento de resultados de 0. Para evitar este problema, asegúrate de que el periodo solicitado con el parámetro non_public_metrics esté dentro de los 30 días más recientes. Además, el valor mínimo de max_results debe ser 10. Estas medidas pueden ayudar a evitar este escenario, pero aún podría ocurrir.
  • Solicitar métricas promocionadas para Posts que no fueron promocionados devuelve una respuesta vacía, en lugar de datos de Post. Nuestro equipo está trabajando actualmente en solucionar este problema.
  • En un Retweet que contiene texto del Post de más de 140 caracteres, el campo text se truncará en lugar de devolver el texto completo del Post. La solución temporal es expandir el Post referenciado y recuperar el texto completo desde la expansión. Este es un error que solucionaremos en el futuro.
Siguientes pasos [Haz tu primera solicitud a un endpoint de Cronologías]/x-api/posts/timelines#getting-started-with-reverse-chronological-home-timeline “Haz tu primera solicitud a un endpoint de Cronologías”) Consulta la lista completa de parámetros, fields y más en nuestras páginas de Referencia de la API Obtén soporte o soluciona un error