Consumo de dados em stream

​

Criando um cliente para consumir dados em tempo real

Ao usar um endpoint de stream, há algumas práticas recomendadas gerais a considerar para otimizar o uso.    

​

Design do cliente

Ao criar uma solução com o endpoint de stream filtrado, você precisará de um cliente que consiga fazer o seguinte:

1. Estabelecer uma conexão HTTPS de streaming com o endpoint de stream filtrado.
2. Enviar solicitações POST de forma assíncrona para o endpoint de regras do stream filtrado para adicionar e DELETE regras do stream.
3. Lidar com baixos volumes de data – manter a conexão de streaming, detectando Objetos Post e sinais de keep-alive.
4. Lidar com altos volumes de data – desacoplar a ingestão do stream do processamento adicional usando processos assíncronos e garantir que os buffers no lado do cliente sejam liberados regularmente.
5. Gerenciar o acompanhamento do consumo de volume no lado do cliente.
6. Detectar desconexões do stream, avaliar e reconectar ao stream automaticamente.  

​

Conectando a um endpoint de streaming

Estabelecer uma conexão com endpoints de streaming da X API v2 significa fazer uma requisição HTTP de longa duração e processar a resposta de forma incremental. Conceitualmente, você pode encarar isso como baixar um arquivo infinitamente longo via HTTP. Uma vez estabelecida a conexão, o servidor da X entregará eventos de Post por meio dela enquanto permanecer aberta.  

​

Consumindo dados

Observe que os campos individuais de objetos JSON não têm uma ordem definida, e nem todos os campos estarão presentes em todas as circunstâncias. Da mesma forma, atividades distintas não são entregues em ordem, e mensagens duplicadas podem ocorrer. Tenha em mente que, ao longo do tempo, novos tipos de mensagens podem ser adicionados e enviados pelo stream.

Assim, seu cliente deve tolerar:

• Campos aparecendo em qualquer ordem
• Campos inesperados ou ausentes
• Posts fora de ordem
• Mensagens duplicadas
• Novos tipos arbitrários de mensagens chegando pelo stream a qualquer momento

Além dos dados relevantes do Post e dos parâmetros de fields solicitados, os seguintes tipos de mensagens podem ser entregues em uma conexão de stream. Observe que esta lista pode não ser abrangente — objetos adicionais podem ser introduzidos nos streams. Certifique-se de que seu parser seja tolerante a formatos de mensagem inesperados.  

​

Bufferização 

Os endpoints de streaming enviarão data para você assim que estiver disponível, o que pode resultar em altos volumes em muitos casos. Se o servidor do X não puder gravar novos data no stream imediatamente (por exemplo, se o seu cliente não estiver lendo rápido o suficiente; veja como lidar com desconexões para mais detalhes), ele armazenará o conteúdo em buffer do lado dele para permitir que seu cliente alcance. No entanto, quando esse buffer estiver cheio, uma desconexão forçada será iniciada para encerrar a conexão, e os Posts em buffer serão descartados e não serão reenviados. Veja abaixo mais detalhes.

Uma forma de identificar quando seu App está ficando para trás é comparar o timestamp dos Posts recebidos com o horário atual e acompanhar isso ao longo do tempo.

Embora acúmulos no stream nunca possam ser completamente eliminados devido à latência potencial e a instabilidades na internet pública, eles podem ser amplamente reduzidos por meio de uma configuração adequada do seu App. Para minimizar a ocorrência de acúmulos:

• Garanta que seu cliente esteja lendo o stream rápido o suficiente. Normalmente, você não deve realizar nenhum processamento pesado enquanto lê o stream. Leia o stream e delegue a atividade a outra thread/process/data store para processar de forma assíncrona.
• Garanta que seu data center tenha largura de banda de entrada suficiente para acomodar grandes volumes sustentados de data, bem como picos significativamente maiores (por exemplo, 5–10x o volume normal). Para o stream filtrado, o volume e a largura de banda correspondente exigidos do seu lado dependem totalmente de quais Posts suas regras estão correspondendo.  

​

Rastreamento de uso e gerenciamento de regras

Como as expectativas dos desenvolvedores sobre qual deve ser o volume de dados “normal” para seus streams variam, não temos uma recomendação geral quanto a uma porcentagem específica de diminuição/aumento ou a um período de tempo.

Considere monitorar os volumes de dados do seu stream para desvios inesperados. Uma queda no volume de dados pode ser sintomática de um problema diferente de uma desconexão do stream. Nessa situação, o stream ainda estaria recebendo o sinal de keep-alive e provavelmente alguns novos dados de atividade. No entanto, uma redução significativa no número de Posts deve levá-lo a investigar se há algo causando a queda no volume de dados recebidos pela sua aplicação ou rede; verifique a página de status para quaisquer avisos relacionados.

Para criar esse monitoramento, você pode acompanhar o número de novos Posts que espera ver em um determinado período de tempo. Se o volume de dados de um stream cair muito abaixo do limite especificado e não se recuperar dentro de um período definido, alertas e notificações devem ser acionados. Você também pode monitorar um grande aumento no volume de dados, particularmente se estiver no processo de modificar regras em um stream filtrado ou se ocorrer um evento que produza um pico na atividade de Posts.

É importante observar que os Posts entregues por meio do stream filtrado contam para o volume mensal total de Posts, e você deve acompanhar e ajustar o consumo para otimizar. Se o volume estiver alto, considere adicionar um operador sample: a cada uma de suas regras para reduzir de 100% de correspondência para sample:50 ou sample:25, quando necessário.

Além disso, incentivamos você a implementar medidas no seu App que alertem sua equipe se o volume ultrapassar um limite predefinido e, possivelmente, adotar outras ações, como exclusão automatizada de regras que estejam trazendo dados em excesso ou desconexão completa do stream em circunstâncias extremas.  

​

Respondendo a mensagens do sistema

Sinais de keep-alive Pelo menos a cada 20 segundos, o stream enviará um sinal de keep-alive (heartbeat) na forma de um retorno de carro \r\n pela conexão aberta para evitar que o seu cliente expire por tempo limite. Seu aplicativo cliente deve tolerar os caracteres \r\n no stream.

Se o seu cliente implementar corretamente um tempo limite de leitura na sua biblioteca HTTP, seu App poderá confiar no protocolo HTTP e na própria biblioteca para gerar um evento se nenhum dado for lido nesse período, e você não precisará monitorar explicitamente o caractere \r\n.

Esse evento geralmente será uma exceção lançada ou algum outro evento, dependendo da biblioteca HTTP utilizada. É altamente recomendável encapsular seus métodos HTTP com manipuladores de erros/eventos para detectar esses timeouts. Em caso de timeout, seu aplicativo deve tentar reconectar.

Mensagens de erro Os endpoints de streaming da v2 também podem entregar mensagens de erro no stream. Abaixo está o formato básico dessas mensagens, junto com alguns exemplos. Observe que as mensagens entregues podem mudar, com novas mensagens sendo introduzidas. Aplicativos clientes precisam tolerar alterações nas cargas de mensagens do sistema.

Observe que as mensagens de erro terão links para a documentação que descreve como resolver o problema.

Formato da mensagem:

	"errors": [{
		"title": "operational-disconnect",
		"disconnect_type": "UpstreamOperationalDisconnect",
		"detail": "Este stream foi desconectado upstream por razões operacionais.",
		"type": "https://api.x.com/2/problems/operational-disconnect"
	}]
}

Observe que mensagens de erro indicando uma desconexão forçada devido a um buffer cheio podem nunca chegar ao seu cliente, se o acúmulo que causou a desconexão forçada impedir sua entrega. Portanto, sua App não deve depender dessas mensagens para iniciar uma nova conexão.