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 al integrar los endpoints de Timelines en tu sistema. Hemos dividido la página en las siguientes secciones:

​
Herramientas útiles

Antes de explorar algunos conceptos clave, recomendamos usar una de las siguientes herramientas o ejemplos de código para comenzar a probar la funcionalidad de estos endpoints. Ejemplos de código ¿Le interesa configurar estos endpoints con código en su lenguaje de programación preferido? Contamos con varios ejemplos de código que puede usar como punto de partida en nuestra página de GitHub. Bibliotecas Aproveche una de nuestras bibliotecas comunitarias de terceros para ayudarle a comenzar. Puede encontrar una biblioteca compatible con los endpoints de v2 buscando la etiqueta de versión adecuada. Postman Postman es una excelente herramienta para probar estos endpoints. Cada solicitud de Postman incluye todas las rutas y parámetros del cuerpo para ayudarle a comprender rápidamente qué está disponible. Para obtener más información sobre nuestras colecciones de Postman, visite 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 conocido como keys and tokens. Puedes usar OAuth 1.0a User Context o OAuth 2.0 Authorization Code with PKCE para autenticar solicitudes a estos endpoints. Puedes usar OAuth 2.0 App-Only para la cronología de Posts de usuario y la cronología de menciones de usuario. OAuth 1.0a User Context requiere que utilices tus API Keys, Access Tokens de usuario y algunos otros parámetros para crear un encabezado de autorización, que luego enviarás con tu solicitud. Los Access Tokens deben estar asociados con el usuario en cuyo nombre estás realizando la solicitud. Si deseas generar un conjunto de Access Tokens para otro usuario, este debe autorizar tu App usando el flujo de OAuth de 3 fases. 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, emplear una herramienta como Postman o usar OAuth 2.0 para autenticar tus solicitudes. Si deseas solicitar un Post o metrics privadas desde estos endpoints, deberás usar OAuth 1.0a User Context o OAuth 2.0 Authorization Code with PKCE, lo cual garantizará que tengas los permisos adecuados del usuario propietario de ese contenido. OAuth 2.0 App-Only solo requiere que envíes un App Access Token de OAuth 2.0 con tu solicitud. Puedes generar un App Access Token directamente dentro de una App de desarrollador o generar uno usando el endpoint POST oauth2/token. Puedes usar esto para la cronología de Posts de usuario o la cronología de menciones de usuario. OAuth 2.0 Authorization Code with 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 específicos 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, ubicada en la sección de configuración del portal de desarrolladores.
Ten en cuentaSi estás solicitando los siguientes fields, se requiere OAuth 1.0a User Context o OAuth 2.0 Authorization Code:
  • 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, Projects 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 App de desarrollador dentro de ese Project. Tus keys and tokens dentro de esa App de desarrollador funcionarán para estos endpoints de cronologías. Límites de velocidad Todos los días, muchos miles de desarrolladores realizan solicitudes a la X API. Para ayudar a gestionar el volumen, se aplican límites de velocidad a cada endpoint que limitan la cantidad de solicitudes que cada desarrollador puede realizar en nombre de una app o en nombre de un usuario autenticado. Se aplican diferentes límites de velocidad para estos endpoints según el método de autenticación que se utilice. Los límites de velocidad a nivel de app se aplican a una App que realiza solicitudes usando OAuth 2.0 App-Only, mientras que el límite de velocidad a nivel de usuario se aplica a solicitudes realizadas en nombre del usuario que autoriza específicamente usando OAuth 1.0a User Context. Estos dos límites de velocidad 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 timelines puede realizar 1500 solicitudes (incluidas las solicitudes de paginación) a la timeline de Posts del usuario y 450 solicitudes (incluidas las solicitudes de paginación) a la timeline 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 realizar 900 solicitudes (incluidas las solicitudes de paginación) a la timeline de Posts del usuario y 180 solicitudes (incluidas las solicitudes de paginación) a la timeline de menciones del usuario por cada usuario autenticado.  La timeline de inicio en orden cronológico inverso tiene un límite de tasa por usuario de 180 solicitudes por ventana de 15 minutos. Con este endpoint puedes obtener todos los Posts creados en una timeline durante los últimos 7 días, así como los 800 más recientes, independientemente de la fecha de creación. Campos y expansions La X API v2 te permite seleccionar exactamente qué data deseas que devuelva la API usando fields y expansions. El parámetro expansions te permite ampliar objetos referenciados en el payload. Por ejemplo, este endpoint te permite solicitar objetos de encuesta, lugar, media y otros utilizando el parámetro expansions. El parámetro fields te permite seleccionar exactamente qué fields dentro de los diferentes objetos de data deseas recibir. De forma predeterminada, el Objeto de Post principal 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 conjuntamente en nuestro diccionario de datos de X API v2. Post metrics Los endpoints de X API v2 te permiten solicitar Post metrics directamente desde el Objeto de Post devuelto, siempre que incluyas los fields adecuados en tu solicitud. Existen algunas limitaciones con las Post metrics de las que debes estar al tanto, específicamente relacionadas con la privacidad del usuario y los siguientes fields de la 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 indicados incluyen datos de metrics privadas, lo que significa que debes estar autorizado por el publicador del Post para recuperar estos datos en su nombre cuando uses el endpoint de timeline 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 timeline de Posts del usuario con ID 1234, deberás incluir access tokens asociados con ese usuario en tu solicitud. Puedes hacer que los usuarios autoricen tu App y recibir un conjunto de access tokens asociados con ellos usando el flujo de OAuth de 3 fases.  Si estás usando la timeline de menciones del usuario, los fields indicados no estarán disponibles a menos que el autor que menciona haya autorizado tu App para acceder a sus datos de metrics privadas y estés utilizando los access tokens de ese usuario al realizar la solicitud con Contexto de usuario de OAuth 1.0a. Todos los 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 indicados, los resultados se ajustarán automáticamente para incluir únicamente Posts de los últimos 30 días. Si se solicitan estos fields indicados, solo se devolverán los Posts cuyo autor sea el usuario autenticado; todos los demás Posts recibirá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 se pueden enviar en una sola respuesta (hasta 100 Posts para los endpoints de timelines), necesitarás 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 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 del usuario también tiene un parámetro exclude que puede eliminar Retweets y respuestas de tus resultados.  Límites de Post y volumen de Posts devueltos Los endpoints de la cronología de Posts del usuario y de menciones al 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 de qué endpoint de cronologías uses, los Posts devueltos contarán para los Post cap a nivel de Project. El uso se muestra en el portal de desarrolladores, y el “mes” comienza el día de renovación de tu suscripción que se muestra en el developer portal dashboard.  El endpoint de la cronología de Posts del 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 incluya 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 del usuario, solo se devolverán los 800 Posts más recientes. El endpoint de la cronología de menciones al 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 Post Los Posts que sean aptos para edición se pueden editar 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 búsqueda o con el endpoint de Post Lookup para confirmar su estado final. Para obtener más información sobre cómo funcionan las ediciones de Post, consulta la página Fundamentos de edición de Posts.   Casos límite
  • Al solicitar metrics no públicas en el endpoint de la cronología de Posts del usuario para Posts que tengan más de 30 días, puedes ver un next_token en la respuesta con un conteo 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 últimos 30 días. Además, el valor mínimo de max_results debe ser 10. Esto puede ayudar a evitar este escenario, pero aún podría ocurrir.
  • Solicitar metrics promocionadas para Posts que no fueron promocionados devuelve una respuesta vacía, en lugar de data de Post. Nuestro equipo está trabajando actualmente en corregir este problema.
  • Para un Retweet que contiene texto del cuerpo 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 corregiremos en el futuro.
Siguientes pasos Realiza tu primera solicitud a un endpoint de cronologías Consulta una 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
⌘I