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

Flujo de Decahose

Enterprise Esta es una API empresarial disponible solo dentro de nuestros niveles de acceso gestionado. Para usar esta API, primero debes crear una cuenta con nuestro equipo de ventas para clientes enterprise. Más información Decahose proporciona una muestra aleatoria del 10% del Firehose en tiempo real de X a través de una conexión de streaming. Esto se logra mediante un algoritmo de muestreo en tiempo real que selecciona los datos de forma aleatoria, al tiempo que permite la entrega de datos con la baja latencia esperada a medida que 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
  • Fiabilidad mejorada - diversidad geográfica de los sistemas de backend
Nota: Estos datos se entregan de forma masiva y no admiten filtrado adicional (por ejemplo, por palabras clave). ENTERPRISE

Transmisión de Me gusta

Esta es una API empresarial disponible solo dentro de nuestros niveles de acceso administrados. Para usar esta API, primero debes configurar una cuenta con nuestro equipo de ventas para empresas. Más información Los Me gusta permiten obtener información sobre quién indica que le gustan las Publicaciones y proporcionan recuentos precisos de Me gusta. Firehose y Decahose de Gnip pueden entregar Me gusta públicos relacionados con las Publicaciones entregadas a través de Gnip. Esto produce métricas de interacción pública y de audiencia en tiempo real asociadas a una Publicación.   Introducción a los Me gusta Al prepararte para consumir datos de Me gusta, debes saber que:
  • Los Me gusta se entregan a través de un stream independiente y separado
  • Históricamente, los Me gusta se denominan “Favorites”. La carga útil en formato nativo enriquecido mantiene esta nomenclatura
  • Los streams incluyen solo Me gusta públicos
    • Público significa que el usuario que da Me gusta, el creador de la Publicación y la Publicación son públicos en la plataforma
  • Los Me gusta son muy similares a los Retweets y representan una señal pública de interacción
  • Los elementos de la carga útil incluyen:
    • Objeto de la Publicación original
    • Objeto actor que creó la Publicación original
    • Objeto actor que realizó la acción de Me gusta
  • Solo se puede dar Me gusta a contenido original
    • No se puede dar Me gusta a Retweets. Un Me gusta de un Retweet se aplica a la Publicación original
    • Los Tweets citados  pueden recibir Me gusta
  • Las actividades de Me gusta incluyen los Gnip Enrichments correspondientes (cuando se han adquirido/aplicado)
  • Productos / funcionalidades compatibles
    • Los streams de Me gusta son compatibles con Backfill (cuando se ha adquirido/aplicado)
    • No hay compatibilidad con Replay para los streams de Me gusta
    • No hay compatibilidad con Search ni Historical para los Me gusta
    • No hay planes inmediatos para añadir 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 para 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 eliminación de Me gusta / «Quitar 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 transmitir grandes volúmenes de Publicaciones en tiempo real, existe un conjunto de prácticas recomendadas que promueven tanto la confiabilidad de los datos como su fidelidad total. 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 reconectarse. Después de reconectarse, es importante evaluar si hubo períodos para los que sea necesario recuperar datos faltantes. El componente que gestiona estos detalles y consume Publicaciones 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 práctica recomendada es disponer de diferentes entornos de streaming, con al menos flujos separados para desarrollo/pruebas y producción. Decahose incluye un conjunto de funcionalidades que ayudan con estos esfuerzos.
  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, en el lado del cliente, haya dos consumidores independientes, idealmente en redes diferentes. Con este diseño, puede haber redundancia entre las redes del lado del cliente, los servidores y las rutas hacia la base de datos. Ten en cuenta que se sirve una copia completa de los datos en cada conexión y que el lado del cliente debe ser tolerante a los datos duplicados y gestionarlos.
  3. Se proporcionará un “heartbeat” cada 10 segundos; sin embargo, con el flujo Decahose, el volumen de datos es lo suficientemente alto como para que incluso una breve duración (por ejemplo, unos pocos segundos) sin Publicaciones 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 Decahose tiene una funcionalidad específica de Recovery y una de Backfill para ayudar a recuperar los datos que se perdieron debido a desconexiones y otros problemas operativos.

Streams adicionales

Contar con streams adicionales de Decahose es otra manera de incorporar mayor confiabilidad en tu solución. Cualquier stream adicional es completamente independiente y tiene su propio endpoint único. A cada stream se le asigna su propio stream_label, y esta etiqueta, junto con el nombre de tu cuenta, forman parte de la URL de ese stream. Consulta el ejemplo a continuación: https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json La convención más común es tener un stream en tiempo real dedicado a tu sistema de producción y un stream adicional disponible para desarrollo y pruebas. Contar con un stream de prueba/desarrollo permite a los clientes de Decahose disponer de un stream para probar actualizaciones de sus clientes consumidores. Aunque 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 puede configurar a través de tu representante de cuenta. Conexiones redundantes Una conexión redundante simplemente te permite establecer más de una conexión simultánea al stream de datos. Esto proporciona redundancia al permitirte conectarte al mismo stream con dos consumidores separados, recibiendo los mismos datos a través de ambas conexiones. Así, tu app cuenta con un failover activo para diversas situaciones, por ejemplo, cuando un stream se desconecta o cuando falla el servidor principal de tu app. La cantidad de conexiones permitidas para un stream determinado se puede configurar a través de tu representante de cuenta. Para usar un stream redundante, simplemente conéctate a la misma URL que usas para tu conexión primaria. Los datos de tu stream se enviarán a través de ambas conexiones, y ambas conexiones de stream se representarán en el panel del stream. Ten en cuenta que, para efectos de facturación, eliminamos los duplicados en los recuentos de actividad que recibes a través de múltiples conexiones, de modo que solo se te facture una vez por cada actividad única. Dado que Decahose tiene dos particiones, aquí tienes 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ías tener la misma cantidad de conexiones en cada partición, así que este ejemplo resalta una situación en la que la conexión redundante a partition=2 se ha interrumpido y deseas investigarla 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 de streaming a una ventana móvil de 5 días de datos históricos recientes de X. Debe utilizarse para recuperar datos en escenarios en los que tu aplicación cliente pierde datos del stream en tiempo real, ya sea debido a una desconexión durante un período corto o por cualquier otro escenario en el que dejes de ingerir datos en tiempo real durante un período de tiempo.

Uso de Recovery

Con el flujo Recovery, tu aplicación puede hacer solicitudes que funcionan de la misma manera que las solicitudes a los flujos en tiempo real. Sin embargo, tu aplicación 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 “Publicaciones desde la hora A hasta la hora B”. Estas Publicaciones se entregan a través de tu conexión de streaming de una manera que imita al flujo 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 Las Publicaciones se entregan comenzando por el primer (más antiguo) minuto del periodo de tiempo especificado y continúan cronológicamente hasta que se entrega el último minuto. En ese momento, se envía a través de la conexión un mensaje Recovery Request Completed y, a continuación, el servidor cierra la conexión. Si tu solicitud comienza en una hora del día en la que hubo pocos o ningún resultado coincidente, es probable que transcurra un periodo de tiempo 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 para entregar, el flujo seguirá enviando retornos de carro, o “heartbeats”, a través de la conexión para evitar que tu conexión agote el tiempo de espera. Recovery está pensado como una herramienta para recuperar fácilmente datos perdidos debido a desconexiones breves, no para periodos de tiempo 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, dos horas) para reducir la posibilidad de que se produzca una desconexión en mitad de la solicitud debido a la volatilidad de Internet u otros motivos, y para proporcionar una mayor visibilidad del progreso de las solicitudes largas.

Disponibilidad de datos

Puedes utilizar la función Recovery 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 streaming recovery te permite disponer de una ventana de backfill ampliada de 24 horas. Recovery te permite “recuperar” el período de tiempo de datos perdidos. Un recovery stream se inicia cuando realizas una solicitud de conexión usando los parámetros de solicitud start_time y end_time. Una vez conectado, Recovery volverá a transmitir el período de tiempo indicado y luego se desconectará.   Puedes realizar 2 solicitudes concurrentes a Recovery al mismo tiempo, es decir, “dos recovery jobs”. Recovery funciona técnicamente de la misma manera que backfill, excepto que se define una hora de inicio y una hora de finalización. Un período de Recovery corresponde a un único intervalo de tiempo.

Relleno histórico

Para solicitar relleno histórico, debes añadir un parámetro backfillMinutes=N a tu solicitud de conexión, donde N es el número de minutos (1-5, solo números enteros) que se rellenarán cuando se establezca la conexión. Por ejemplo, si te desconectas durante 90 segundos, deberías añadir backfillMinutes=2 a tu solicitud de conexión. Dado que esta solicitud proporcionará relleno histórico durante 2 minutos, incluido el periodo de 30 segundos anterior a tu desconexión, tu aplicación consumidora debe ser tolerante a los datos duplicados. Un ejemplo de URL de solicitud de conexión de Decahose, que pide un relleno histórico de 5 minutos para la partición 1, es el siguiente: 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” cuando te conectes y luego gestionar cualquier dato duplicado que se proporcione.
  • Si estás desconectado durante más de cinco minutos, puedes recuperar datos usando Recovery.
Recuperarse de una desconexión Reiniciar y recuperarse de una desconexión implica varios pasos:
  • Determinar la duración del periodo 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, haz una solicitud de Recovery para el periodo de tiempo desconectado (idealmente con tu conjunto de reglas de tiempo real actual, 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
    Backfill te permite reconectarte desde un punto anterior a la desconexión de una conexión de 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 enviarse al mismo entorno en vivo, desduplicando los datos, eliminarás la necesidad de recuperación a menos que TANTO el stream normal como el stream redundante experimenten tiempo de inactividad o desconexiones simultáneas. Si el stream redundante no puede enviarse en vivo al entorno de producción, se puede escribir en un almacén de datos “de emergencia” separado. Entonces, 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 periodo de tiempo en el que falten datos.
  3. Implementar Recovery
    Cuando las desconexiones o el tiempo de inactividad afecten tanto al stream principal como al stream redundante, utiliza 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 cada vez y transmitiéndola en streaming. Esto se hace en paralelo al stream en tiempo real. Ten en cuenta que no tenemos soluciones para recuperar datos de Decahose más allá de la ventana de 5 días proporcionada por Recovery, por lo que es importante que utilices un stream redundante para asegurarte de que dispones de una copia completa de los datos de tu lado en caso de un tiempo de inactividad significativo.
Cuando detectes volúmenes de datos almacenados anormales: 
Posibles formas de detectar datos faltantes cuando no se han producido desconexiones ni tiempo de inactividad…
  1. Contar Publicaciones entrantes
    Tu sistema debería contar el número bruto de Publicaciones que recibes al inicio de tu aplicación de ingesta y luego proporcionar una forma de comparar esos números con el número de Publicaciones que llega a tu almacén de datos final. Cualquier diferencia puede supervisarse y servir para alertar a tu equipo sobre problemas que estén causando que los datos se pierdan después de ser recibidos.
  2. Analizar volúmenes almacenados anormales
    También puedes analizar los volúmenes de datos almacenados en tu base de datos final para buscar caídas anormales. Esto también puede indicar problemas, aunque probablemente habrá circunstancias en las que las caídas de volumen sean normales (por ejemplo, si la plataforma de X no está disponible y las personas no pueden crear Publicaciones durante algún periodo de tiempo).

Referencia de la API

Decahose stream

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

Métodos

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

Autenticación

Todas las solicitudes a las Volume Stream APIs deben utilizar autenticación básica HTTP (HTTP Basic Authentication), construida a partir de una combinación válida de dirección de correo electrónico y contraseña usada para iniciar sesión en tu cuenta en console.gnip.com. Las credenciales deben enviarse en el encabezado Authorization en cada solicitud. Por lo tanto, confirma que tu cliente esté agregando el encabezado HTTP “Authentication: Basic” (con las credenciales codificadas a través de HTTPS) a todas las solicitudes a la API.

GET :stream

Establece una conexión persistente con el stream Firehose, mediante 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.
URLSe encuentra en la página de ayuda de la API del stream en tu panel de control, usando 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 poder consumir el stream completo. Deberás 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 de la siguiente manera:

Accept-Encoding: gzip
Codificación de caracteresUTF-8
Formato de la respuestaJSON. El encabezado de tu solicitud debe especificar el formato JSON para la respuesta.
Límite de frecuencia10 solicitudes cada 60 segundos.
Parámetro BackfillSi has adquirido un stream con Backfill habilitado, deberás agregar el parámetro “backfillMinutes” en la solicitud GET para habilitarlo.
Read TimeoutConfigura un tiempo de espera de lectura en tu cliente y asegúrate de que esté establecido en un valor superior a 30 segundos.
Compatibilidad con ediciones de TweetsTodos los objetos Tweet incluirán metadatos de edición que describen el historial de ediciones del Tweet. Consulta la página de conceptos básicos “Edit Tweets” para obtener más detalles.

Responses

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 de texto con detalles adicionales en el cuerpo. Para respuestas distintas de 200, los clientes deben intentar reconectarse.
StatusTextDescription
200SuccessLa conexión se abrió correctamente y se enviarán nuevas actividades a medida que vayan llegando.
401UnauthorizedLa 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.
406Not AcceptableGeneralmente, esto ocurre cuando tu cliente no incluye correctamente los encabezados para aceptar la codificación gzip desde el flujo (stream), pero 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 (stream) mientras se lee en el extremo del cliente.”
429Rate LimitedTu aplicación ha superado el límite de solicitudes de conexión.
503Service UnavailableProblema del servidor de X. Vuelve a conectarte utilizando un patrón de reintentos con retroceso exponencial. Si no se ha publicado ningún aviso sobre este problema en la X API Status Page, contacta al soporte o al servicio de emergencia si no puedes conectarte después de 10 minutos.

Ejemplo de solicitud curl

La siguiente solicitud de ejemplo se realiza usando cURL en la línea de comandos. Sin embargo, tenga en cuenta que estas solicitudes también se pueden enviar con el lenguaje de programación de su elección:
curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/firehose/accounts/:account\_name/publishers/twitter/:stream\_label.json?partition={#}"

Replay API

La Replay API es un complemento importante de los streams 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.