Pular para o conteúdo principal
Este endpoint foi atualizado para incluir metadata de edição de Post. Saiba mais sobre essa metadata na página de fundamentos “Editar Posts”.

​
Decahose stream

Enterprise Esta é uma API Enterprise disponível apenas nos nossos níveis de acesso gerenciados. Para usar esta API, você deve primeiro configurar uma conta com nossa equipe de vendas Enterprise. Saiba mais O Decahose fornece uma amostra aleatória de 10% do X Firehose em tempo real por meio de uma conexão de stream. Isso é feito por meio de um algoritmo de amostragem em tempo real que seleciona os dados aleatoriamente, ao mesmo tempo que mantém a entrega de baixa latência esperada conforme os dados são enviados pelo firehose pela X. Abaixo estão alguns dos recursos disponíveis com o Decahose:
  • URLs expandidas e aprimoradas: - desfaz completamente URLs encurtadas e fornece metadata adicional (título e descrição da página)
  • Particionamento de stream - 2 partições, cada uma contendo 50% do volume do stream Decahose
  • Confiabilidade aprimorada - diversidade geográfica dos sistemas de backend
Observação: Esses dados são entregues em lote e não oferecem suporte a filtragem adicional (por exemplo, por palavras-chave). ENTERPRISE

​
Transmitindo likes

Esta é uma API Enterprise disponível apenas nos nossos níveis de acesso gerenciados. Para usar esta API, você deve primeiro configurar uma conta com nossa equipe de vendas Enterprise. Saiba mais Likes permitem identificar quem curte Posts e fornecem contagens precisas de likes. O Firehose e o Decahose da Gnip podem entregar likes públicos relacionados aos Posts fornecidos via Gnip. Isso gera métricas de engajamento público em tempo real e de audiência associadas a um Post. Como começar com Likes Ao se preparar para consumir dados de likes, você deve saber que:
  • Likes são entregues por meio de um stream independente
  • Likes são historicamente chamados de “Favorites”. O payload no formato nativo enriquecido mantém essa nomenclatura
  • Os streams incluem apenas likes públicos
    • Público significa que o usuário que deu like, o criador do Post e o próprio Post são públicos na plataforma
  • Likes são muito semelhantes a Retweets e representam um sinal público de engajamento
  • Os elementos do payload incluem:
    • Objeto Post original
    • Objeto Actor que criou o Post original
    • Objeto Actor que realizou a ação de like
  • Apenas conteúdo original pode receber like
    • Retweets não podem receber like. Um like em um Retweet é aplicado ao Post original
    • Tweets com citação podem receber like
  • As atividades de like incluem Gnip Enrichments aplicáveis (quando adquiridos/aplicados)
  • Produtos / Recursos compatíveis
    • Streams de likes oferecem suporte a Backfill (quando adquirido/aplicado)
    • Não há suporte a Replay para streams de likes
    • Não há suporte de Search ou Historical para likes
    • Não há planos imediatos de adicionar suporte a likes ao PowerTrack
Decahose Payload no 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
   }
}
Payload de DELETE de like / “unlike” 
{
   "delete":{
      "favorite":{
         "tweet_id":696615514970279937,
         "tweet_id_str":"696615514970279937",
         "user_id":2510287578,
         "user_id_str":"2510287578"
      },
      "timestamp_ms":"1480437031205"
   }
}

​
Guias

​
Recuperação e Redundância

Introdução  Com o streaming de grandes volumes de Posts em tempo real, há um conjunto de práticas recomendadas que promovem tanto a confiabilidade quanto a fidelidade total dos dados. Ao consumir dados em tempo real, maximizar o tempo de conexão é um objetivo fundamental. Quando ocorrerem desconexões, é importante detectá-las automaticamente e reconectar. Após reconectar, é importante avaliar se houve períodos para realizar backfill dos dados. O componente que gerencia esses detalhes e consome Posts em tempo real é apenas uma parte de um sistema com considerações de rede, datastore, servidor e armazenamento. Dada a complexidade desses sistemas, outra prática recomendada é ter diferentes ambientes de streaming, com pelo menos streams separados para desenvolvimento/testes e produção. O Decahose inclui um conjunto de recursos que ajuda nesses esforços.
  1. Para oferecer suporte a vários ambientes, podemos implantar Additional Streams para sua conta. Esses streams são independentes entre si e têm um stream_label diferente para ajudar a diferenciá-los.
  2. Para ajudar a manter uma conexão, cada stream do Decahose oferece suporte a Redundant Connections. A arquitetura mais comum é um stream ter duas conexões e, no lado do cliente, haver dois consumidores independentes — idealmente em redes diferentes. Com esse design, pode haver redundância entre as redes do lado do cliente, servidores e caminhos do datastore. Observe que uma cópia completa dos dados é entregue em cada conexão e o lado do cliente deve ser tolerante a e gerenciar dados duplicados.
  3. Um “heartbeat” será enviado a cada 10 segundos; no entanto, com o stream do Decahose, o volume de dados é alto o suficiente para que até mesmo uma pequena duração (por exemplo, alguns segundos) sem Posts possa indicar um problema de conexão. Portanto, tanto um “silêncio de dados” quanto a ausência de um heartbeat podem ser usados para detectar uma desconexão.
Como desconexões acontecerão, o stream do Decahose conta com recursos dedicados de Recovery e Backfill para ajudar a recuperar dados que foram perdidos devido a desconexões e outros problemas operacionais.

​
Streams adicionais

Ter streams Decahose adicionais é outra forma de aumentar a confiabilidade da sua solução. Streams adicionais são completamente independentes e possuem seu próprio endpoint. Cada stream recebe seu próprio stream_label e esse rótulo, juntamente com o nome da sua conta, fazem parte da URL desse stream. Veja o exemplo abaixo: https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json A convenção mais comum é ter um stream em tempo real dedicado ao seu sistema de produção e um stream adicional disponível para desenvolvimento e testes. Ter um stream de teste/desenvolvimento permite que clientes do Decahose tenham um stream para testar atualizações dos consumidores do cliente. Embora qualquer rótulo (exclusivo) possa ser atribuído a um stream, uma convenção é usar ‘prod’ para o stream de produção e ‘dev’ ou ‘sandbox’ para um stream adicional de desenvolvimento. O número de streams e seus rótulos exclusivos é configurável pelo seu representante de conta. Conexões redundantes Uma conexão redundante simplesmente permite estabelecer mais de uma conexão simultânea ao data stream. Isso fornece redundância ao permitir que você se conecte ao mesmo stream com dois consumidores distintos, recebendo os mesmos dados em ambas as conexões. Assim, seu App tem um failover ativo para várias situações, por exemplo, quando um stream é desconectado ou quando o servidor primário do seu App falha. O número de conexões permitidas para qualquer stream é configurável pelo seu representante de conta. Para usar um stream redundante, basta se conectar à mesma URL usada para sua conexão primária. Os dados do seu stream serão enviados por ambas as conexões, com ambas as conexões de stream representadas no painel do stream. Observe que, para fins de cobrança, deduplicamos as contagens de atividades que você recebe por meio de múltiplas conexões, de modo que você seja cobrado apenas uma vez por cada atividade exclusiva. Como o Decahose tem duas partições, segue abaixo um exemplo de como funciona a contagem de conexões: Connect to decahose partition=1 Connect to decahose partition=1 Connect to decahose partition=2 A situação acima resulta em um total de três conexões — duas conexões para partition=1 e uma conexão para partition=2. Normalmente, você desejaria o mesmo número de conexões para cada partition, então este exemplo destaca uma situação em que a conexão redundante para partition=2 caiu e você deve investigar mais a fundo. Recuperação

​
Visão geral 

Recovery é uma ferramenta de recuperação de dados (não deve ser usada para a coleta primária de dados) que oferece acesso em streaming a uma janela móvel de 5 dias de dados históricos recentes da X. Ela deve ser utilizada para recuperar dados em cenários em que o seu aplicativo consumidor perde dados no stream em tempo real, seja devido a uma desconexão por um curto período ou por qualquer outra situação em que você deixe de ingerir dados em tempo real por algum tempo.

​
Usando o Recovery 

Com o stream Recovery, sua App pode fazer solicitações que funcionam da mesma forma que as solicitações aos streams em tempo real. No entanto, sua App deve especificar parâmetros na URL que indiquem a janela de tempo desejada. Em outras palavras, uma solicitação de Recovery pede à API: “Posts do tempo A ao tempo B.” Esses Posts são então entregues por meio da sua conexão de streaming de uma maneira que imita o stream em tempo real, porém em uma taxa ligeiramente abaixo do tempo real. Veja abaixo um exemplo: “https://stream-data-api.x.com/stream/powertrack/accounts/someAccountName/publishers/twitter/powertrack.json?startTime=2023-07-05T17:09:12.070Z” Os Posts são entregues começando pelo primeiro (mais antigo) minuto do período especificado, seguindo em ordem cronológica até que o minuto final seja entregue. Nesse ponto, uma mensagem Recovery Request Completed é enviada pela conexão e, em seguida, a conexão é encerrada pelo servidor. Se sua solicitação começar em um horário com poucos ou nenhum resultado correspondente, provavelmente haverá um intervalo antes de os primeiros resultados serem entregues — os dados serão enviados quando o Recovery encontrar correspondências na parte do arquivo que estiver sendo processada naquele momento. Quando não houver resultados disponíveis para entregar, o stream continuará enviando caracteres de retorno de carro, ou “heartbeats”, pela conexão para evitar timeout. O Recovery se destina a ser uma ferramenta para recuperar facilmente dados perdidos devido a desconexões curtas, não para períodos muito longos, como um dia inteiro. Se surgir a necessidade de recuperar dados por longos períodos, recomendamos dividir solicitações mais extensas em janelas menores (por exemplo, duas horas) para reduzir a possibilidade de desconexão no meio da solicitação devido à volatilidade da internet ou outros motivos e para proporcionar mais visibilidade sobre o progresso de solicitações longas.

​
Disponibilidade de dados

Você pode usar o recurso Recovery para recuperar dados perdidos nas últimas 24 horas caso não consiga se reconectar dentro da janela de backfill de 5 minutos. O recurso de recuperação em streaming permite uma janela de backfill estendida de 24 horas. Recovery permite “recuperar” o período de tempo de dados perdidos. Um stream de recuperação é iniciado quando você faz uma solicitação de conexão usando os parâmetros de solicitação ‘start_time’ e ‘end_time’. Depois de conectado, o Recovery fará o re-stream do período indicado e, em seguida, se desconectará.   Você poderá fazer 2 solicitações simultâneas ao Recovery ao mesmo tempo, ou seja, “dois jobs de recovery”. Recovery funciona tecnicamente da mesma forma que backfill, exceto pelo fato de que um horário de início e de término é definido. Um período de recovery corresponde a um único intervalo de tempo.

​
Backfill

Para solicitar backfill, você precisa adicionar o parâmetro backfillMinutes=N à sua solicitação de conexão, em que N é o número de minutos (1–5, apenas inteiros) a serem recuperados quando a conexão for estabelecida. Por exemplo, se você ficar desconectado por 90 segundos, deve adicionar backfillMinutes=2 à sua solicitação de conexão. Como essa solicitação fornecerá backfill por 2 minutos, incluindo os 30 segundos anteriores à desconexão, seu app consumidor deve tolerar dados duplicados. Um exemplo de URL de solicitação de conexão Decahose, pedindo um backfill de 5 minutos para a partição 1, é: https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1&backfillMinutes=5 NOTAS:
  • Você pode optar por sempre usar ‘backfillMinutes=5’ ao se conectar e, em seguida, tratar quaisquer dados duplicados fornecidos.
  • Se você ficar desconectado por mais de cinco minutos, poderá recuperar dados usando Recovery.
Recuperando de uma desconexão Reiniciar e se recuperar de uma desconexão envolve várias etapas:
  • Determinar a duração do período de desconexão.
    • 5 minutos ou menos?
      • Se você tiver o Backfill habilitado para o stream, prepare a solicitação de conexão com o parâmetro ‘backfillMinutes’ apropriado.
    • Mais de 5 minutos?
      • Se você tiver um stream de Recovery, faça uma solicitação de Recovery para o período desconectado (idealmente com seu conjunto de regras de tempo real atual, usando a Rules API, se necessário).
  • Solicitar uma nova conexão.
Quando você passar por desconexões ou indisponibilidade, seguem estratégias para mitigar e se recuperar nesse cenário:
  1. Implementar backfill O backfill permite reconectar a partir de um ponto anterior à desconexão de um stream e cobre desconexões de até 5 minutos. Ele é implementado incluindo um parâmetro na solicitação de conexão.
  2. Consumir um stream redundante de outro local Se o stream redundante puder ser enviado para o mesmo ambiente em produção, com deduplicação de dados, você eliminará a necessidade de recuperação, a menos que AMBOS o stream normal e o redundante tenham indisponibilidade ou desconexões simultâneas. Se o stream redundante não puder ser enviado em tempo real para o ambiente de produção, ele pode ser gravado em um repositório de dados “de emergência” separado. Então, no caso de desconexões ou indisponibilidade na conexão do stream primário, seu sistema terá dados disponíveis para preencher seu banco de dados primário no período em que os dados estiverem ausentes.
  3. Implementar Recovery Quando desconexões ou indisponibilidade afetarem tanto o stream primário quanto o redundante, use o Decahose Recovery para recuperar quaisquer dados perdidos. A API fornece uma janela rolante de 5 dias do arquivo e é melhor utilizá-la solicitando no máximo uma hora dessa janela por vez e transmitindo-a. Isso é feito em paralelo ao stream em tempo real. Observe que não temos soluções para recuperar dados do Decahose além da janela de 5 dias fornecida por Recovery, portanto, é importante utilizar um stream redundante para garantir que você tenha uma cópia completa dos dados do seu lado em caso de indisponibilidade significativa.
Quando você detectar volumes anormais de dados armazenados — Maneiras potenciais de detectar dados ausentes quando não ocorreram desconexões ou indisponibilidade…
  1. Contar Posts recebidos Seu sistema deve contar o número bruto de Posts recebidos logo no início do seu app de ingestão e, em seguida, fornecer uma forma de comparar esses números ao número de Posts que chegam ao repositório de dados final. Quaisquer diferenças podem ser monitoradas e alertar sua equipe sobre problemas que estejam causando perda de dados após o recebimento.
  2. Analisar volumes armazenados anormais Você também pode analisar os volumes de dados armazenados no seu banco de dados final para procurar quedas anormais. Isso pode indicar problemas, embora provavelmente haja circunstâncias em que quedas de volume sejam normais (por exemplo, se a plataforma X estiver indisponível e as pessoas não conseguirem criar Posts por algum período).

​
Referência da API

​
Decahose stream

Ir para esta página Métodos Autenticação GET /{stream-type}/:stream Replay API

​
Métodos

MétodoDescrição
GET /{stream-type}/:streamConectar ao stream de dados

​
Autenticação

Todas as solicitações às APIs de Volume Stream devem usar autenticação básica HTTP, construída a partir de uma combinação válida de endereço de e-mail e senha usada para acessar sua conta em console.gnip.com. As credenciais devem ser enviadas no cabeçalho Authorization em cada solicitação. Portanto, verifique se o seu cliente está adicionando o cabeçalho HTTP “Authorization: Basic” (com as credenciais codificadas sobre HTTPS) a todas as solicitações da API.

​
GET :stream

Estabelece uma conexão persistente com o stream Firehose, por meio da qual os dados em tempo real serão fornecidos.

​
Especificações da solicitação

Método da solicitaçãoHTTP GET
Tipo de conexãoKeep-Alive

Isso deve ser especificado no cabeçalho da solicitação.
URLDisponível na página de Ajuda da API do stream no seu painel, usando a seguinte estrutura:

Decahose:

https://gnip-stream.x.com/stream/sample10/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1
Partição (obrigatória)partition=\{#} - A definição de partição agora é obrigatória para consumir o stream completo. Você precisará se conectar ao stream com o parâmetro de partição especificado. Abaixo está o número de partições por stream:

* Decahose: 2 partições
CompressãoGzip. Para se conectar ao stream usando compressão Gzip, basta enviar um cabeçalho Accept-Encoding na solicitação de conexão. O cabeçalho deve ser o seguinte:

Accept-Encoding: gzip
Codificação de caracteresUTF-8
Formato da respostaJSON. O cabeçalho da sua solicitação deve especificar o formato JSON para a resposta.
Limite de taxa10 solicitações a cada 60 segundos.
Parâmetro de BackfillSe você adquiriu um stream com Backfill ativado, será necessário adicionar o parâmetro “backfillMinutes” na solicitação GET para ativá-lo.
Timeout de leituraDefina um timeout de leitura no seu cliente e garanta que ele esteja configurado para um valor acima de 30 segundos.
Suporte a edições de TweetTodos os objetos de Tweet incluirão metadata de edição de Tweet descrevendo o histórico de edições do Tweet. Consulte a página de fundamentos “Edit Tweets” para mais detalhes.

​
Respostas

As seguintes respostas podem ser retornadas pela API para essas solicitações. A maioria dos códigos de erro é retornada com uma string com detalhes adicionais no corpo. Para respostas diferentes de 200, os clientes devem tentar reconectar.
StatusTextoDescrição
200SucessoA conexão foi aberta com sucesso e novas atividades serão enviadas conforme forem recebidas.
401Não autorizadoA autenticação HTTP falhou devido a credenciais inválidas. Faça login em console.gnip.com com suas credenciais para garantir que você as está utilizando corretamente na sua solicitação.
406Não aceitávelGeralmente, isso ocorre quando o seu cliente não inclui corretamente os cabeçalhos para aceitar codificação gzip do stream, mas também pode ocorrer em outras circunstâncias.

Conterá uma mensagem JSON semelhante a “Esta conexão requer compressão. Para habilitar a compressão, envie um cabeçalho ‘Accept-Encoding: gzip’ na sua solicitação e esteja pronto para descompactar o stream conforme ele é lido no lado do cliente.”
429Limite de taxa excedidoSeu App excedeu o limite de solicitações de conexão.
503Serviço indisponívelProblema no servidor do X. Reconecte usando um padrão de backoff exponencial. Se nenhum aviso sobre esse problema tiver sido publicado na X API Status Page, entre em contato com o suporte ou acione o atendimento de emergência se não for possível conectar após 10 minutos.

​
Exemplo de solicitação curl

O exemplo a seguir usa cURL na linha de comando. No entanto, observe que essas solicitações também podem ser feitas na linguagem de programação de sua preferência: 
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

A Replay API é um complemento importante aos streams de Volume em tempo real. O Replay é uma ferramenta de recuperação de dados que fornece acesso contínuo, via stream, a uma janela dinâmica dos dados históricos recentes da X.
⌘I