Saltar al contenido principal
Este endpoint se actualizó para incluir metadatos de edición de Posts. Obtén más información sobre estos metadatos en la página de fundamentos “Editar Posts”.

​
Flujo Decahose

Empresarial Esta es una API empresarial disponible únicamente dentro de nuestros niveles de acceso gestionados. Para usar esta API, primero debe crear una cuenta con nuestro equipo de ventas empresariales. Más información Decahose ofrece una muestra aleatoria del 10% del X Firehose en tiempo real a través de una conexión de streaming. Esto se logra mediante un algoritmo de muestreo en tiempo real que selecciona los datos aleatoriamente, a la vez que permite la entrega con la baja latencia esperada conforme X los envía a través del firehose. A continuación se muestran algunas de las funcionalidades disponibles con Decahose:
  • URL ampliadas y mejoradas: - expande por completo las URL acortadas y proporciona metadatos adicionales (título y descripción de la página)
  • Particionado del flujo - 2 particiones, cada una con el 50% del volumen del flujo de Decahose
  • Mayor confiabilidad - diversidad geográfica de los sistemas de backend
Nota: Estos datos se entregan en bloque y no admiten filtrado adicional (p. ej., por palabras clave). ENTERPRISE

​
Transmisión de Me gusta

Esta es una API Empresarial disponible únicamente dentro de nuestros niveles de acceso gestionados. Para usar esta API, primero debe configurar una cuenta con nuestro equipo de ventas Empresarial. Más información Los Me gusta permiten saber quién interactúa con un Post y ofrecen recuentos precisos de Me gusta. Firehose y Decahose de Gnip pueden entregar Me gusta públicos relacionados con los Posts suministrados a través de Gnip. Esto proporciona métricas de participación pública y de audiencia en tiempo real asociadas a un Post.   Primeros pasos con los Me gusta A medida que se prepara para consumir datos de Me gusta, debe tener en cuenta que:
  • Los Me gusta se entregan mediante un flujo independiente y separado
  • Históricamente, los Me gusta se denominaron “Favoritos”. La carga útil en formato nativo enriquecido mantiene esta nomenclatura
  • Los flujos incluyen únicamente Me gusta públicos
    • Público significa que el usuario que da Me gusta, el creador del Post y el Post son públicos en la plataforma
  • Los Me gusta son muy similares a los Retweets y representan una señal pública de participación
  • Los elementos de la carga útil incluyen:
    • Objeto Post original
    • Objeto actor que creó el Post original
    • Objeto actor que realizó la acción de dar Me gusta
  • Solo se puede dar Me gusta al contenido original
    • No se puede dar Me gusta a los Retweets. Un Me gusta a un Retweet se aplica al Post original
    • Los Tweets citados pueden recibir Me gusta
  • Las actividades de Me gusta incluyen las Gnip Enrichments aplicables (cuando se hayan adquirido/aplicado)
  • Productos/funciones compatibles
    • Los flujos de Me gusta admiten Backfill (cuando se haya adquirido/aplicado)
    • No hay compatibilidad con Replay para los flujos de Me gusta
    • No hay compatibilidad con Search ni Historical para los Me gusta
    • No hay planes inmediatos de agregar compatibilidad de Me gusta a PowerTrack
Decahose Carga útil en formato nativo enriquecido 
{
   "id":"43560406e0ad9f68374445f5f30c33fc",
   "created_at":"Thu Dec 01 22:27:39 +0000 2016",
   "timestamp_ms":1480631259353,
   "favorited_status":{
      "created_at":"Thu Dec 01 22:27:16 +0000 2016",
      "id":804451830033948672,
      "id_str":"804451830033948672",
      "text":"@kafammheppduman",
      "source":"\u003ca href=\"http:\/\/x.com\/download\/android\" rel=\"nofollow\"\u003eX for Android\u003c\/a\u003e",
      "truncated":false,
      "in_reply_to_status_id":803694205163814912,
      "in_reply_to_status_id_str":"803694205163814912",
      "in_reply_to_user_id":2855759795,
      "in_reply_to_user_id_str":"2855759795",
      "in_reply_to_screen_name":"kafammheppduman",
      "user":{
         "id":2855759795,
         "id_str":"2855759795",
         "name":"delirdim kanka",
         "screen_name":"kafammheppduman",
         "location":"sanane",
         "url":"http:\/\/instagram.com\/kafammheppduman",
         "description":"Manit @GalatasaraySk \ud83d\udc9e",
         "translator_type":"none",
         "protected":false,
         "verified":false,
         "followers_count":3702,
         "friends_count":607,
         "listed_count":1,
         "favourites_count":113338,
         "statuses_count":389,
         "created_at":"Sat Nov 01 22:38:25 +0000 2014",
         "utc_offset":null,
         "time_zone":null,
         "geo_enabled":true,
         "lang":"tr",
         "contributors_enabled":false,
         "is_translator":false,
         "profile_background_color":"C0DEED",
         "profile_background_image_url":"",
         "profile_background_image_url_https":"",
         "profile_background_tile":false,
         "profile_link_color":"1DA1F2",
         "profile_sidebar_border_color":"C0DEED",
         "profile_sidebar_fill_color":"DDEEF6",
         "profile_text_color":"333333",
         "profile_use_background_image":true,
       "Profile_image_url": "http:\/\/pbs.twimg.com\/profile_images\/804421763945861121\/v3bp9pnq_normal.jpg",
         "Profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/804421763945861121\/v3bp9pnq_normal.jpg",
         "profile_banner_url":"https:\/\/pbs.twimg.com\/profile_banners\/2855759795\/1480630085",
         "default_profile":true,
         "default_profile_image":false,
         "following":null,
         "follow_request_sent":null,
         "notifications":null
      },
      "geo":null,
      "coordinates":null,
      "place":null,
      "contributors":null,
      "is_quote_status":false,
      "retweet_count":0,
      "favorite_count":0,
      "entities":{
         "hashtags":[],
         "urls":[],
         "user_mentions":[
            {
               "screen_name":"kafammheppduman",
               "name":"delirdim kanka",
               "id":2855759795,
               "id_str":"2855759795",
               "indices":[
                  0,
                  16
               ]
            }
         ],
         "symbols":[]
      },
      "favorited":false,
      "retweeted":false,
      "filter_level":"low",
      "lang":"und"
   },
   "user":{
      "id":774146932365070336,
      "id_str":"774146932365070336",
      "name":"Uyuyan Adam",
      "screen_name":"saykoMenn",
      "location":"Tarsus, T\u00fcrkiye",
      "url":"http:\/\/connected2.me\/pmc1i",
      "description":null,
      "translator_type":"none",
      "protected":false,
      "verified":false,
      "followers_count":414,
      "friends_count":393,
      "listed_count":0,
      "favourites_count":9868,
      "statuses_count":370,
      "created_at":"Fri Sep 09 07:26:26 +0000 2016",
      "utc_offset":null,
      "time_zone":null,
      "geo_enabled":false,
      "lang":"tr",
      "contributors_enabled":false,
      "is_translator":false,
      "profile_background_color":"F5F8FA",
      "profile_background_image_url":"",
      "profile_background_image_url_https":"",
      "profile_background_tile":false,
      "profile_link_color":"1DA1F2",
      "profile_sidebar_border_color":"C0DEED",
      "profile_sidebar_fill_color":"DDEEF6",
      "profile_text_color":"333333",
      "profile_use_background_image":true,
      "Profile_image_url": "http:\/\/pbs.twimg.com\/profile_images\/802992813424201728\/VMzcTL3x_normal.jpg",
      "Profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/802992813424201728\/VMzcTL3x_normal.jpg",
      "profile_banner_url":"https:\/\/pbs.twimg.com\/profile_banners\/774146932365070336\/1480283382",
      "default_profile":true,
      "default_profile_image":false,
      "following":null,
      "follow_request_sent":null,
      "notifications":null
   }
}
Carga útil de Me gusta / “No me gusta” 
{
   "delete":{
      "favorite":{
         "tweet_id":696615514970279937,
         "tweet_id_str":"696615514970279937",
         "user_id":2510287578,
         "user_id_str":"2510287578"
      },
      "timestamp_ms":"1480437031205"
   }
}

​
Guías

​
Recuperación y Redundancia

Introducción  Al hacer streaming de altos volúmenes de Posts en tiempo real, existe un conjunto de mejores prácticas que fomentan tanto la confiabilidad de los datos como su fidelidad íntegra. Al consumir datos en tiempo real, maximizar el tiempo de conexión es un objetivo fundamental. Cuando se producen desconexiones, es importante detectarlas automáticamente y reconectar. Tras reconectar, es importante evaluar si hubo periodos para los que se deba completar datos faltantes. El componente que gestiona estos detalles y consume Posts en tiempo real es solo una parte de un sistema con consideraciones de red, base de datos, servidor y almacenamiento. Dada la complejidad de estos sistemas, otra buena práctica es disponer de distintos entornos de streaming, con al menos flujos separados para desarrollo/pruebas y producción. Decahose incluye un conjunto de funciones que ayudan con estos objetivos.
  1. Para admitir múltiples entornos, podemos implementar Additional Streams para tu cuenta. Estos flujos son independientes entre sí y tienen un stream_label diferente para ayudar a diferenciarlos.
  2. Para ayudar a mantener una conexión, cada flujo de Decahose admite Redundant Connections. La arquitectura más común es que un flujo tenga dos conexiones y, del lado del cliente, haya dos consumidores independientes, idealmente en redes diferentes. Con este diseño, puede haber redundancia en las redes, servidores y rutas de la base de datos del lado del cliente. Ten en cuenta que en cada conexión se sirve una copia completa de los datos y que el lado del cliente debe ser tolerante y gestionar datos duplicados.
  3. Se enviará un “heartbeat” cada 10 segundos; sin embargo, con el flujo de Decahose, el volumen de datos es lo suficientemente alto como para que incluso una breve duración (p. ej., unos segundos) sin Posts pueda indicar un problema de conexión. Por lo tanto, tanto un “silencio de datos” como la falta de un heartbeat pueden utilizarse para detectar una desconexión.
Dado que las desconexiones ocurrirán, el flujo de Decahose cuenta con funciones dedicadas de Recovery y Backfill para ayudar a recuperar los datos que se perdieron debido a desconexiones y otros problemas operativos.

​
Streams adicionales

Contar con streams de Decahose adicionales es otra forma de incorporar confiabilidad en su solución. Cada stream adicional es completamente independiente y tiene su propio endpoint. A cada stream se le asigna su propio stream_label, y esta etiqueta, junto con el nombre de su cuenta, forman parte de la URL de ese stream. Vea el siguiente ejemplo: https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json La convención más común es disponer de un stream en tiempo real dedicado para su sistema de producción y un stream adicional para desarrollo y pruebas. Tener un stream de prueba/desarrollo permite a los clientes de Decahose contar con un flujo para probar actualizaciones del cliente consumidor. Si bien se puede asignar cualquier etiqueta (única) a un stream, una convención es usar ‘prod’ para el stream de producción y ‘dev’ o ‘sandbox’ para un stream adicional de desarrollo. La cantidad de streams, y sus etiquetas únicas, se configura a través de su representante de cuenta. Conexiones redundantes Una conexión redundante simplemente le permite establecer más de una conexión simultánea al stream de data. Esto brinda redundancia al permitirle conectarse al mismo stream con dos consumidores distintos, recibiendo la misma data a través de ambas conexiones. Así, su App cuenta con un failover en caliente para diversas situaciones, por ejemplo, cuando un stream se desconecta o cuando falla el servidor principal de su App. La cantidad de conexiones permitidas para cualquier stream dado se configura a través de su representante de cuenta. Para usar un stream redundante, simplemente conéctese a la misma URL usada para su conexión principal. La data de su stream se enviará a través de ambas conexiones, y ambas conexiones de stream se mostrarán en el panel del stream. Tenga en cuenta que, a efectos de facturación, deduplicamos los conteos de actividad que recibe a través de múltiples conexiones, de modo que solo se le facture una vez por cada actividad única. Dado que Decahose tiene dos particiones, a continuación se muestra un ejemplo de cómo funciona el conteo de conexiones: Connect to decahose partition=1 Connect to decahose partition=1 Connect to decahose partition=2 La situación anterior da como resultado un total de tres conexiones: dos conexiones a partition=1 y una conexión a partition=2. Normalmente, querrá la misma cantidad de conexiones en cada partición, por lo que este ejemplo destaca una situación en la que la conexión redundante a partition=2 se ha caído y desea investigarlo más a fondo. Recuperación

​
Descripción general 

Recovery es una herramienta de recuperación de datos (no debe usarse para la recopilación principal de datos) que proporciona acceso por streaming a una ventana continua de 5 días de datos históricos recientes de X. Debe utilizarse para recuperar datos en escenarios en los que tu App consumidora pierde datos del flujo en tiempo real, ya sea por una desconexión breve o cualquier otra situación en la que no consigas ingerir datos en tiempo real durante un período.

​
Uso de Recovery 

Con el stream de Recovery, tu App puede realizar solicitudes que funcionan de la misma manera que las solicitudes a los streams en tiempo real. Sin embargo, tu App debe especificar parámetros en la URL que indiquen la ventana de tiempo que estás solicitando. En otras palabras, una solicitud de Recovery le pide a la API “Posts desde la hora A hasta la hora B”. Estos Posts se entregan a través de tu conexión de streaming de una forma que imita el stream en tiempo real, pero a una velocidad ligeramente inferior al tiempo real. Consulta el siguiente ejemplo: “https://stream-data-api.x.com/stream/powertrack/accounts/someAccountName/publishers/twitter/powertrack.json?startTime=2023-07-05T17:09:12.070Z” Los Posts se entregan comenzando por el primer (más antiguo) minuto del periodo de tiempo especificado, y continúan de forma cronológica hasta que se entrega el último minuto. En ese momento, se envía un mensaje de Recovery Request Completed a través de la conexión y el servidor cierra la conexión. Si tu solicitud comienza en un momento del día en el que hubo pocos o ningún resultado coincidente, probablemente transcurra un periodo antes de que se entreguen los primeros resultados; los datos se entregarán cuando Recovery encuentre coincidencias en la parte del archivo que se esté procesando en ese momento. Cuando no haya resultados disponibles que entregar, el stream seguirá enviando retornos de carro, o “latidos”, a través de la conexión para evitar que se agote el tiempo de espera. Recovery está pensado como una herramienta para recuperar fácilmente datos perdidos debido a desconexiones breves, no para periodos muy largos como un día completo. Si surge la necesidad de recuperar datos durante periodos prolongados, recomendamos dividir las solicitudes más largas en ventanas de tiempo más cortas (por ejemplo, de dos horas) para reducir la posibilidad de desconexión a mitad de la solicitud por inestabilidad de internet u otros motivos, y para proporcionar mayor visibilidad sobre el progreso de solicitudes largas.

​
Disponibilidad de datos

Puedes usar la función de Recuperación para recuperar datos perdidos en las últimas 24 horas si no puedes volver a conectarte dentro de la ventana de backfill de 5 minutos. La función de recuperación de streaming te permite contar con una ventana de backfill ampliada de 24 horas. La Recuperación te permite “recuperar” el período de tiempo de los datos perdidos. Se inicia un flujo de recuperación cuando realizas una solicitud de conexión usando los parámetros de solicitud “start_time” y “end_time”. Una vez conectado, Recuperación volverá a transmitir el período de tiempo indicado y luego se desconectará. Podrás realizar 2 solicitudes de recuperación concurrentes al mismo tiempo, es decir, “dos trabajos de recuperación”. Técnicamente, la Recuperación funciona de la misma manera que el backfill, excepto que se define una hora de inicio y una hora de fin. Un período de recuperación corresponde a un único intervalo de tiempo.

​
Backfill

Para solicitar backfill, debes agregar el parámetro backfillMinutes=N a tu solicitud de conexión, donde N es la cantidad de minutos (1-5, solo números enteros) que se recuperarán cuando se establezca la conexión. Por ejemplo, si te desconectas durante 90 segundos, debes agregar backfillMinutes=2 a tu solicitud de conexión. Dado que esta solicitud proporcionará backfill durante 2 minutos, incluido el período de 30 segundos anterior a la desconexión, tu App consumidora debe tolerar datos duplicados. Un ejemplo de URL de solicitud de conexión de Decahose, que pide un backfill de 5 minutos para la partición 1, es: https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1&backfillMinutes=5 NOTAS:
  • Tienes la opción de usar siempre “backfillMinutes=5” al conectarte y luego gestionar cualquier dato duplicado que se proporcione.
  • Si estás desconectado por más de cinco minutos, puedes recuperar datos usando Recovery.
Recuperación tras una desconexión Reiniciar y recuperarse de una desconexión implica varios pasos:
  • Determinar la duración del período de desconexión.
    • ¿5 minutos o menos?
      • Si tienes backfill habilitado para el stream, prepara la solicitud de conexión con el parámetro “backfillMinutes” apropiado.
    • ¿Más de 5 minutos?
      • Si tienes un stream de Recovery, realiza una solicitud de Recovery para el período de tiempo desconectado (idealmente con tu conjunto de reglas actual en tiempo real, usando la Rules API si es necesario).
  • Solicitar una nueva conexión.
Cuando experimentes desconexiones o tiempo de inactividad, estas son estrategias para mitigar y recuperarte en este escenario:
  1. Implementar backfill El backfill te permite reconectarte desde un punto anterior a la desconexión de un stream y cubre desconexiones de hasta 5 minutos. Se implementa incluyendo un parámetro en la solicitud de conexión.
  2. Consumir un stream redundante desde otra ubicación Si el stream redundante puede transmitirse al mismo entorno en vivo y deduplicar los datos, eliminarás la necesidad de recuperación a menos que TANTO el stream normal como el redundante experimenten tiempo de inactividad o desconexiones simultáneas. Si el stream redundante no puede transmitirse en vivo al entorno de producción, puede escribirse en un almacén de datos “de emergencia” separado. Luego, en caso de desconexiones o tiempo de inactividad en la conexión del stream principal, tu sistema tendrá datos disponibles para completar tu base de datos principal durante el período en que falten datos.
  3. Implementar Recovery Cuando las desconexiones o el tiempo de inactividad afecten tanto al stream principal como al redundante, usa Decahose Recovery para recuperar cualquier dato perdido. La API proporciona una ventana móvil que cubre 5 días del archivo y se aprovecha mejor solicitando no más de una hora de esa ventana por vez y transmitiéndola. Esto se realiza en paralelo al stream en tiempo real. Ten en cuenta que no existen soluciones para recuperar datos de Decahose más allá de la ventana de 5 días que proporciona Recovery, por lo que es importante utilizar un stream redundante para asegurarte de contar con una copia completa de los datos de tu lado en caso de un tiempo de inactividad significativo.
Cuando detectes volúmenes de datos almacenados anómalos: Formas potenciales de detectar datos faltantes cuando no hubo desconexiones ni tiempo de inactividad…
  1. Contar los Posts entrantes Tu sistema debe contar el número bruto de Posts que recibes al inicio de tu App de ingesta y luego proporcionar una forma de comparar esos números con la cantidad de Posts que llega a tu almacén de datos final. Cualquier diferencia puede monitorearse y alertar a tu equipo sobre problemas que hagan que se descarten datos después de recibirlos.
  2. Analizar volúmenes almacenados anómalos También puedes analizar los volúmenes de datos almacenados en tu base de datos final para buscar caídas anómalas. Esto puede indicar problemas, aunque probablemente habrá circunstancias en las que las caídas de volumen sean normales (por ejemplo, si la plataforma X no está disponible y las personas no pueden crear Posts durante algún período de tiempo).

​
Referencia de la API

​
Flujo Decahose

Ir a en esta página Métodos Autenticación GET /{stream-type}/:stream API de Replay

​
Métodos

MétodoDescripción
GET /{stream-type}/:streamConectar al flujo de datos

​
Autenticación

Todas las solicitudes a las API de Volume Stream deben usar Autenticación HTTP Básica, creada a partir de una combinación válida de dirección de correo electrónico y contraseña utilizada para iniciar sesión en su cuenta en console.gnip.com. Las credenciales deben enviarse en el encabezado Authorization de cada solicitud. Por lo tanto, confirme que su cliente esté agregando el encabezado HTTP “Authorization: Basic” (con credenciales codificadas sobre HTTPS) a todas las solicitudes a la API.

​
GET :stream

Establece una conexión persistente con el flujo Firehose, a través de la cual se entregarán los datos en tiempo real.

​
Especificaciones de la solicitud

Método de la solicitudHTTP GET
Tipo de conexiónKeep-Alive

Esto debe especificarse en el encabezado de la solicitud.
URLDisponible en la página de Ayuda de la API del stream en tu panel, con la siguiente estructura:

Decahose:

https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1
Partición (obligatoria)partition=\{#} - Ahora la partición es obligatoria para consumir el stream completo. Debes conectarte al stream con el parámetro de partición especificado. A continuación se muestra el número de particiones por stream:

* Decahose: 2 particiones
CompresiónGzip. Para conectarte al stream usando compresión Gzip, simplemente envía un encabezado Accept-Encoding en la solicitud de conexión. El encabezado debe verse así:

Accept-Encoding: gzip
Codificación de caracteresUTF-8
Formato de respuestaJSON. El encabezado de tu solicitud debe especificar JSON como formato de la respuesta.
Límite de frecuencia10 solicitudes cada 60 segundos.
Parámetro de BackfillSi compraste un stream con Backfill habilitado, debes agregar el parámetro “backfillMinutes” en la solicitud GET para habilitarlo.
Tiempo de espera de lecturaConfigura un tiempo de espera de lectura en tu cliente y asegúrate de que sea superior a 30 segundos.
Compatibilidad con ediciones de TweetTodos los objetos de Tweet incluirán metadatos de edición del Tweet que describen su historial de ediciones. Consulta la página de fundamentos “Edit Tweets” para más detalles.

​
Respuestas

Las siguientes respuestas pueden ser devueltas por la API para estas solicitudes. La mayoría de los códigos de error se devuelven con una cadena con información adicional en el cuerpo. Para respuestas distintas de 200, los clientes deben intentar reconectarse.
EstadoTextoDescripción
200CorrectoLa conexión se abrió correctamente y las nuevas actividades se enviarán a medida que lleguen.
401No autorizadoLa autenticación HTTP falló debido a credenciales no válidas. Inicia sesión en console.gnip.com con tus credenciales para asegurarte de que las estás usando correctamente en tu solicitud.
406No aceptableGeneralmente, esto ocurre cuando tu cliente no incluye correctamente los encabezados para aceptar la codificación gzip del flujo, aunque también puede ocurrir en otras circunstancias.

Contendrá un mensaje JSON similar a: “Esta conexión requiere compresión. Para habilitar la compresión, envía un encabezado ‘Accept-Encoding: gzip’ en tu solicitud y prepárate para descomprimir el flujo a medida que se lee en el lado del cliente.”
429Límite de frecuencia excedidoTu App ha superado el límite de solicitudes de conexión.
503Servicio no disponibleProblema del servidor de X. Vuelve a conectar usando un patrón de retroceso exponencial. Si no se ha publicado un aviso sobre este problema en la X API Status Page, contacta al soporte o a emergencias si no puedes conectarte después de 10 minutos.

​
Ejemplo de solicitud con curl

La siguiente solicitud de ejemplo se realiza con curl desde la línea de comandos. No obstante, tenga en cuenta que estas solicitudes también pueden enviarse con el lenguaje de programación de su preferencia: 
curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/firehose/accounts/:account_name/publishers/twitter/:stream_label.json?partition={#}"

​
API de Replay

La API de Replay es un complemento importante para los flujos de Volumen en tiempo real. Replay es una herramienta de recuperación de datos que ofrece acceso por streaming a una ventana deslizante de datos históricos recientes de X.