Como escrever um cliente nativo Twitter para MetaTrader: 2º parte

Introdução

Como prometi no primeiro artigo "Como escrever um cliente nativo Twitter para MetaTrader 4 e MetaTrader 5 sem usar DLL", na segunda parte tentaremos explorar as possibilidades da Twitter API para o envio de tweets com imagens. Para não carregar o artigo com detalhes desnecessários, nos concentraremos apenas na publicação de imagens. Ao final deste artigo, como resultado deveremos ter um cliente Twitter funcionando sem usar nenhuma DLL externa, o que permitirá a postagem de tweets com até quatro imagens. Quatro imagens é o número máximo permitido na Twitter API, de acordo com o parâmetro media_ids.

Carregando imagens

À API foi adicionado o novo método chunked upload para fazer upload de mídia, permitindo carregar arquivos grandes com mais eficiência, como vídeos ou GIFs animados. Para nossos propósitos, como apenas iremos fazer upload de imagens, precisaremos só de um método simples.

Antes de começar a trabalhar, é imprescindível ler os requisitos e restrições sobre os tipos e tamanhos de arquivos de mídia no Twitter.

Na verdade, o upload de uma foto no Twitter é uma simples solicitação POST multipart/form-data com autorização OAuth. Vamos falar sobre isso na próxima seção. Para cada imagem carregada, é retornado um identificador media_id, que só é válido por um determinado período — ele deve ser anexado no tweet publicado.

Ao publicar quatro imagens, você simplesmente escreve todos os media_id retornados, separados por vírgulas.

Para postar uma mensagem com imagens, siga estas etapas:

1. Faça upload da imagem e pegue o media_id retornado
2. Repita o upload de imagens - até 4. Sempre pegue o media_id retornado
3. Prepare sua mensagem
4. Ao enviar uma mensagem para inserir imagens, especifique sua lista de identificadores media_id, separados por vírgulas

Observação: para não complicar o código, eu ignorei aqui o processamento de erros.

HTTP multipart/form-data

Ao postar um tweet, é possível fazer o upload das imagens como dados brutos binários ou como uma string Base64. É recomendável usar o formato de dados brutos binários, uma vez que a linha Base64 será mais ou menos três vezes maior em tamanho.

O método HTTP multipart/form-data é definido em RFC-2388, mas pode ser melhor compreendido com ajuda desse excelente material sobre curl. De acordo com esse material, ele é "uma solicitação HTTP POST enviada junto com o corpo da solicitação como um conjunto formatado de partes com MIME boundaries."

POST /submit.cgi HTTP/1.1
Host: example.com
User-Agent: curl/7.46.0
Accept: */*
Content-Length: 313
Expect: 100-continue
Content-Type: multipart/form-data; boundary=------------------------d74496d66958873e

--------------------------d74496d66958873e
Content-Disposition: form-data; name="person"

anonymous
--------------------------d74496d66958873e
Content-Disposition: form-data; name="secret"; filename="file.txt"
Content-Type: text/plain

contents of the file
--------------------------d74496d66958873e--

Implementação na classe Twitter:

   void              appendPhoto(string filename, string hash, uchar &data[],
                                 bool common_flag=false)
     {
      int flags=FILE_READ|FILE_BIN|FILE_SHARE_WRITE|FILE_SHARE_READ;
      if(common_flag)
         flags|=FILE_COMMON;
      //---
      int handle=FileOpen(filename,flags);
      if(handle==INVALID_HANDLE)
         return;
      //---
      int size=(int)FileSize(handle);
      uchar img[];
      ArrayResize(img,size);
      FileReadArray(handle,img,0,size);
      FileClose(handle);
      int pos = ArraySize(data);
      int offset = pos + size;
      int hlen = StringLen(hash)+6;
      int newlen = offset + hlen;
      ArrayResize(data, newlen);
      ArrayCopy(data, img, pos);
      StringToCharArray("\r\n--"+hash+"\r\n", data, offset, hlen);
     }

Neste código, o arquivo de imagem binário é adicionado à "parte" da solicitação HTTP POST multipart/form-data. Em seguida, no código é mostrado o envelope da solicitação POST com especificação do parâmetro Twitter Upload-API media.

   string              uploadPhoto(string filename)
     {
      // POST multipart/form-data
      string url = "https://upload.twitter.com/1.1/media/upload.json";
      //string url = "https://httpbin.org/anything";
      string params[][2];
      string query = oauthRequest(params, url, "POST");
      string o = getOauth(params);
      string custom_headers = "Content-Type: multipart/form-data;"
                              " boundary=";
      string boundary = getNonce();
      StringAdd(custom_headers, boundary); // use nonce as boundary string
      StringAdd(custom_headers, "\r\n");
      string headers = getHeaders(o, custom_headers, "upload.twitter.com");

      //string query = getQuery(params, url);
      //Print(query);
      uchar data[];
      string part = "\r\n--";
      StringAdd(part, boundary);
      StringAdd(part, "\r\nContent-Disposition: form-data;"
                " name=\"media\"\r\n\r\n");
      StringToCharArray(part, data, 0, StringLen(part));
      appendPhoto(filename, boundary, data);
      string resp = SendRequest("POST", url, data, headers);;
      if(m_verbose)
        {
         SaveToFile(filename + "_post.txt", data);
         Print(resp);
        }
      return (getTokenValue(resp, "media_id"));
     }

Para verificar o funcionamento de HTTP multipart/form-data, salvamos a solicitação HTTP numa arquivo na pasta de dados do terminal MetaTrader.

Tweet com imagens

Aqui estou usando uma a função getTokenValue() mais simples para obter o media_id, retornado pela interface da Twitter Upload-API. Você pode aproveitar a excelente biblioteca MQL5 para trabalhar com o protocolo JSON. 

A seguir é mostrado um exemplo simples de como usar a classe Twitter. A função Screenshots() faz capturas de telas dos gráficos abertos no momento e compõe um tweet simples. É possível selecionar até quatro gráficos. Cada captura de tela é salva num arquivo, enquanto o nome do arquivo é retornado na matriz de string fnames.

As capturas de tela são carregadas uma de cada vez, os identificadores media_id retornados são coletados numa lista, separados por vírgulas. Ao especificar os identificadores media_id numa lista como essa, nos estamos publicando uma mensagem no Twitter com nossas capturas de tela.

Tudo é bem simples.

   CTwitter tw(consumer_key, consumer_secret,
               access_token, access_secret, verbose);

   // Gather information
   string fnames[4];
   string msg;
   Screenshots(fnames, msg);

   // Upload screenshots
   int n = ArraySize(fnames);
   int i = n - 1;
   // create comma separated media_ids
   string medias = tw.uploadPhoto(fnames[i]);
   for(i= n - 2; i>=0; i--)
   {
      StringAdd(medias, ",");
      StringAdd(medias, tw.uploadPhoto(fnames[i]));
   }
   
   // Send Tweet with photos' ids
   string resp = tw.tweet(msg, medias);
   Print(resp);

Classe Twitter

A classe Twitter no Twitter.mqh é um arquivo autônomo que não depende de outros arquivos include. Em outras palavras, para postar gráficos no Twitter, você só precisa de um arquivo.

Primeiro, é necessário instanciar o objeto Twitter, após especificar o token de cliente e de acesso, além disso, é possível especificar o sinalizador "verbose", para ajudar a realizar a depuração.

   CTwitter tw(consumer_key, consumer_secret,
               access_token, access_secret, verbose);

Em seguida, você pode tentar chamar as funções public disponíveis:

• verifyCredentials() 
  Retorna o Twitter ID para seu token de acesso.

• uploadPhoto()
  Carrega uma imagem e retorna seu identificador media_id.

• tweet()
  Envia um tweet com identificador media_id.

Existem várias funções auxiliares:

• getTokenValue()
  Retorna o valor do token/parâmetro a partir de uma string json.
  Observação: este é um exemplo muito simples, não espere compatibilidade total com json.

• unquote()
  Remove as aspas de uma string.

Publicação de gráficos no Twitter

Ao artigo está anexado um script MT5 simples que tira até quatro capturas de tela de gráficos e compõe uma mensagem simples com o nome do símbolo e o valor OHLCV.

Com base neste exemplo simples, você pode começar a desenvolver scripts e EAs próprios.

Observação: inclua seus tokens e chaves secretas em seu código.

A seguir são mostrados exemplos de tweets publicados pelo script.

Figura 1. Tweet com fotos enviadas desde MT5

Fig. 2. Tweet com gráfico desde o MetaTrader 5 em tamanho real 

Certamente, você pode postar qualquer foto.

Fig. 3. Tweet com gatos do Dalai Lama

Fim do artigo

Bem, criamos uma classe simples do Twitter na forma de arquivo de inclusão separado. Ela permite publicar tweets com gráficos e alertas. A minha intenção é que os detalhes técnicos apresentados sejam fáceis de entender.

Isto está longe de ser uma classe completa, e há muito mais para adicionar a partir de outras interfaces da Twitter API. Compartilhe suas ideias nos comentários.

Desejo que tenha gostado de ler este artigo tanto quanto gostei de escrevê-lo. Espero que os tweets se tornem divertidos e lucrativos.

Aproveite seu uso!