Saltar al contenido principal

​
Cómo integrar los puntos de conexión de búsqueda de Publicaciones

Esta página contiene información sobre varias herramientas y conceptos clave que debes conocer al integrar en tu sistema los puntos de conexión de búsqueda reciente o de archivo completo. Hemos dividido la página en las siguientes secciones:

​
Herramientas útiles

Antes de comenzar a explorar algunos conceptos clave, le recomendamos usar una de las siguientes herramientas o ejemplos de código para empezar a probar la funcionalidad de estos puntos de conexión.

​
Ejemplos de código

¿Le interesa configurar estos puntos de conexión con código en su lenguaje de programación preferido? Tenemos varios ejemplos de código disponibles que puede usar como punto de partida en nuestra página de GitHub, incluidos un cliente de Python y un cliente de Ruby.

​
Bibliotecas

Aprovecha una de nuestras bibliotecas comunitarias de terceros para empezar. Puedes encontrar una biblioteca compatible con los puntos de conexión de la v2 buscando la etiqueta de versión correspondiente.

​
Postman

Postman es una excelente herramienta que puede usar para probar estos puntos de conexión. Cada solicitud de Postman incluye todos los parámetros del punto de conexión correspondiente para ayudarle a comprender rápidamente qué está disponible para usted. Para obtener más información sobre nuestras colecciones de Postman, visite nuestra página Uso de Postman.  

​
Conceptos clave

​
Autenticación

Todos los puntos de conexión de X API v2 requieren que autentiques tus solicitudes con un conjunto de credenciales, también conocidas como claves y tokens. Puedes usar OAuth 1.0a User Context, OAuth 2.0 App-Only o Código de autorización de OAuth 2.0 con PKCE para autenticar tus solicitudes al punto de conexión de búsqueda reciente. Debes usar OAuth 2.0 App-Only cuando utilices el punto de conexión de búsqueda de archivo completo. OAuth 2.0 App-Only solo requiere que envíes un OAuth 2.0 App Access Token con tu solicitud. Puedes generar un App Access Token directamente en una App para desarrolladores o generar uno usando el punto de conexión POST oauth2/token. OAuth 1.0a User Context requiere que utilices tus API Keys, Tokens de Acceso de usuario y otros parámetros para crear un encabezado de autorización, que luego enviarás con tu solicitud. Los Tokens de Acceso deben estar asociados con el usuario en cuyo nombre realizas la solicitud. Si deseas generar un conjunto de Tokens de Acceso para otro usuario, ese usuario debe autorizar tu App usando 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 usar OAuth 2.0 para autenticar tus solicitudes. Si deseas solicitar una Publicación o métricas privadas desde estos puntos de conexión, deberás usar OAuth 1.0a User Context 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. Código de autorización de OAuth 2.0 con PKCE permite un mayor control sobre el alcance (scope) de una aplicación y flujos de autorización en múltiples dispositivos. OAuth 2.0 te permite elegir ámbitos 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, ubicada en la sección de configuración de la App en el portal para desarrolladores.
Ten en cuentaSi solicitas los siguientes campos, se requiere OAuth 1.0a User Context 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 para desarrolladores, Proyectos y Apps para desarrolladores Para trabajar con cualquier punto de conexión de X API v2, debes registrarte para obtener una cuenta de desarrollador, configurar un Proyecto dentro de esa cuenta y crear una App para desarrolladores dentro de ese Proyecto. Las claves y tokens de esa App para desarrolladores funcionarán con estos puntos de conexión de búsqueda. Puedes usar claves y tokens de un Proyecto con cualquier nivel de acceso para realizar solicitudes al punto de conexión de búsqueda reciente. Sin embargo, deberás usar un Proyecto con nivel de acceso Pro o Enterprise para realizar solicitudes al punto de conexión de búsqueda del archivo completo. Si tienes acceso Enterprise, contarás con funcionalidades adicionales, como más operadores disponibles y consultas de mayor longitud.  

​
Límites de tasa

Cada día, muchos miles de desarrolladores realizan solicitudes a la X API. Para ayudar a gestionar el volumen, se aplican límites de tasa a cada punto de conexión que restringen la cantidad de solicitudes que cada desarrollador puede realizar en nombre de una app o de un usuario autenticado. Existen diferentes límites de tasa para estos puntos de conexión según el método de autenticación utilizado. Los límites de tasa a nivel de app se aplican a una app que realiza solicitudes mediante OAuth 2.0 App-Only, mientras que el límite de tasa a nivel de usuario se aplica a las solicitudes realizadas en nombre del usuario que otorga la autorización mediante OAuth 1.0a User Context o Código de autorización de OAuth 2.0 con PKCE. Ambos límites de tasa se basan en la frecuencia de solicitudes dentro de una ventana de 15 minutos. Por ejemplo, una app que utiliza OAuth 2.0 App-Only para realizar solicitudes al punto de conexión de búsqueda reciente puede realizar 450 solicitudes (incluidas las solicitudes de paginación) dentro de un período de 15 minutos. Esa misma app, dentro del mismo período de 15 minutos y con dos usuarios autenticados diferentes (usando OAuth 1.0a User Context o Código de autorización de OAuth 2.0 con PKCE), puede realizar hasta 180 solicitudes (incluidas las solicitudes de paginación) al punto de conexión de búsqueda reciente por cada usuario autenticado.  

​
Campos y expansiones

X API v2 le permite seleccionar exactamente qué datos desea que se devuelvan desde la API usando campos y expansiones. El parámetro expansions le permite ampliar los objetos referenciados en el payload. Por ejemplo, este punto de conexión le permite solicitar objetos de encuesta, lugar, medios y otros usando el parámetro expansions. Los parámetros fields le permiten seleccionar exactamente qué campos dentro de los distintos objetos de datos desea recibir. De forma predeterminada, el objeto principal de la Publicación devuelto por estos puntos de conexión incluye los campos id y text (además de edit_history_tweet_ids para Publicaciones creadas después de que se lanzó esa función). Para recibir campos adicionales como author_id o public_metrics, deberá solicitarlos específicamente usando los parámetros fields. Algunos campos importantes que podría considerar usar en su integración son nuestros datos de encuestas, métricas, anotaciones de la Publicación y los campos de conversation ID. Hemos añadido una guía sobre cómo usar campos y expansiones conjuntamente en nuestro diccionario de datos de X API v2.  

​
Métricas

Los puntos de conexión de X API v2 te permiten solicitar métricas directamente de los objetos devueltos, siempre que incluyas los campos adecuados en tu solicitud. Existen algunas limitaciones con las métricas de Publicaciones que debes tener en cuenta, específicamente relacionadas con la privacidad del usuario y los siguientes campos 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 campos indicados incluyen datos de métricas privadas; esto significa que debes estar autorizado por la persona que publicó la Publicación para recuperar estos datos en su nombre cuando uses el punto de conexión de búsqueda reciente, es decir, debes usar OAuth 1.0a User Context. Dado que este método de autenticación solo se puede usar con la búsqueda reciente, no podrás recuperar estas métricas mediante el punto de conexión de búsqueda del archivo completo. Por ejemplo, para recibir non_public_metrics de las Publicaciones del usuario con id 1234, tendrás que incluir Tokens de Acceso asociados con ese usuario en tu solicitud. Puedes hacer que los usuarios autoricen tu aplicación y obtener un conjunto de Tokens de Acceso asociados a ellos mediante el flujo OAuth de 3 patas. Todas las non_public_metrics, organic_metrics y promoted_metrics solo están disponibles para Publicaciones creadas en los últimos 30 días. Esto significa que, cuando solicites los campos indicados, los resultados se ajustarán automáticamente para incluir únicamente Publicaciones de los últimos 30 días. Si se solicitan estos campos, solo se devolverán las Publicaciones creadas por el usuario autenticado; todas las demás Publicaciones devolverán un mensaje de error.  

​
Creación de consultas de búsqueda

La función principal de estos puntos de conexión es el uso de una única consulta de búsqueda para filtrar las Publicaciones que se te entregan. Estas consultas están compuestas por operadores que hacen coincidir atributos de la Publicación y del usuario, como palabras clave del mensaje, hashtags y URL. Los operadores pueden combinarse en consultas con lógica booleana y paréntesis para refinar el comportamiento de coincidencia de la consulta. Puedes consultar nuestra guía sobre cómo crear una consulta para obtener más información. Estos puntos de conexión 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 Publicaciones para la búsqueda reciente y 500 para la búsqueda en el archivo completo), será necesario 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 en nuestra guía de paginación.

​
Límites de Publicaciones

Los puntos de conexión de búsqueda de Publicaciones tienen un límite en la cantidad de Publicaciones que pueden devolver en un mes determinado, independientemente de la paginación. Independientemente del punto de conexión de búsqueda que utilices, las Publicaciones devueltas contarán para los límites de Publicaciones a nivel de Proyecto. El uso se muestra en el portal para desarrolladores, y el “mes” comienza en el día de renovación de tu suscripción que se muestra en el panel del portal para desarrolladores. Ediciones de Publicaciones Las Publicaciones que sean aptas para edición se pueden editar hasta cinco veces en los 30 minutos posteriores a la publicación de la Publicación original. Los puntos de conexión de búsqueda siempre proporcionarán la versión más reciente de la Publicación. Si solo solicitas Publicaciones que se publicaron hace 30 minutos o más, siempre recibirás la versión final de la Publicación. Sin embargo, si tienes un caso de uso casi en tiempo real y estás consultando Publicaciones publicadas en los últimos treinta minutos, esas Publicaciones podrían haberse editado después de que las recibieras. Estas Publicaciones se pueden rehidratar con la búsqueda o con el punto de conexión de Post Lookup para confirmar su estado final. Para obtener más información sobre cómo funcionan las ediciones de Publicaciones, consulta la página Aspectos fundamentales de las ediciones de Publicaciones.   Próximos pasos Realiza tu primera solicitud a un punto de conexión de búsqueda de Publicaciones Consulta la lista completa de parámetros, campos y más en nuestras páginas de referencia de la API Obtén soporte o soluciona un error