Serialização e desserialização de mensagens¶

Para serializar e desserializar mensagens enviadas para e do backend do cTrader, pode usar Protocol Buffers (Protobufs) ou JSON (JavaScript Object Notation).

Abaixo, definimos cada método de serialização e deserialização em detalhe.

JSON ¶

Os objetos JSON podem ser definidos como simples pares chave-valor. Note que as chaves são sempre strings enquanto os valores podem ser de diferentes tipos de dados, como mostrado no exemplo abaixo.

{
    "clientMsgId": "cm_id_2",
    "payloadType": 2100,
    "payload": {
        "keyOne": [1, 2, 10,],
        "keyTwo": "valueTwo",
    }
}

No exemplo, o valor da chave "clientMsgId" é uma string enquanto o valor da chave "payloadType" é um inteiro. A chave "payload" contém outro objeto JSON que está aninhado no corpo do objeto pai. O valor da chave "payload.keyOne" é uma lista de inteiros.

Saiba como pode enviar e receber JSON.

Protocol Buffers ¶

Protocol Buffers (ou Protobufs) oferecem um mecanismo neutro em termos de linguagem e plataforma, extensível para serializar dados estruturados. Ao usar Protobufs, pode codificar dados estruturados num formato eficiente mas extensível.

Com Protobufs, só precisa de definir uma vez como quer que os seus dados sejam estruturados. Isto é feito especificando tipos de mensagem Protobuf em ficheiros .proto.

Cada mensagem Protobuf é um registo de informação contendo uma série de pares nome-valor. Abaixo, pode encontrar um exemplo básico de um ficheiro .proto que define uma mensagem contendo informação sobre uma pessoa.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

message Person {

    required string name = 1;  
    required int32 id = 2;  
    optional string email = 3;  


    enum PhoneType {  
        MOBILE = 0;  
        HOME = 1;  
        WORK = 2;  
    }  

    message PhoneNumber {  
       required string number = 1;  
       optional PhoneType type = 2 [default = HOME];  
    }  

    repeated PhoneNumber phone = 4;  
}

Como pode ver, o formato da mensagem é simples. Cada tipo de mensagem tem um ou mais campos numerados de forma única, e cada campo tem um nome e um tipo de valor, onde os tipos de valor podem ser números (inteiros ou vírgula flutuante), booleanos, strings, bytes brutos ou até mesmo (como no exemplo acima) outros tipos de mensagem Protocol Buffer, permitindo estruturar os seus dados hierarquicamente.

Pode encontrar mais informação sobre como escrever ficheiros .proto no guia de linguagem Protocol Buffer.

Saiba mais sobre Protocol Buffers.

Veja um tutorial sobre enviar e receber Protobufs.

ProtoMessages ¶

Ao trabalhar com Protobufs, estará a enviar e receber objetos ProtoMessage desenhados pela Spotware.

Para lidar com a fragmentação de rede, o envio de mensagens usa a seguinte estrutura de frame.

1
2
3
4

 +--------------------------+-----------------------------------------+  
 | Message Length (4 bytes) | Serialized ProtoMessage object (byte[]) |  
 +--------------------------+-----------------------------------------+  
                            |<---------- Message Length ------------->|

Cada ProtoMessage tem a seguinte estrutura.

1
2
3
4
5

 +----------------------+  
 | int32 payloadType    |  
 | byte[] payload       |  
 | string clientMsgId   |  
 +----------------------+

A estrutura contém dois campos obrigatórios.

• payloadType. Contém o ID ProtoPayloadType. Este campo denota o tipo do objeto Protobuf serializado no campo payload.
• payload. Contém a mensagem Protobuf serializada real que corresponde ao payloadType.

Um outro campo é opcional.

• clientMsgId. Contém o ID da mensagem que é atribuído pelo cliente.

A definição real do ProtoMessage é a seguinte.

1
2
3
4
5
6
7
8

message ProtoMessage {  
    required uint32 payloadType = 1; //Contains the ID of the ProtoPayloadType or other
    custom PayloadTypes (e.g. ProtoCHPayloadType).  
    optional bytes payload = 2; //The serialised Protobuf message that corresponds to
    the payloadType.  
    optional string clientMsgId = 3; //The request message ID which is assigned by the
    client.  
}

Convenção de nomenclatura¶

As mensagens Protobuf que formam a Open API do cTrader podem ser categorizadas nos seguintes tipos:

• Mensagens de pedido
• Mensagens de resposta
• Mensagens de evento
• Mensagens de modelo

Mensagens de pedido¶

As mensagens de pedido são utilizadas para solicitar informações ao backend do cTrader ou executar várias operações.

As mensagens de pedido são marcadas com Req no final dos seus respetivos nomes. Por exemplo, a mensagem ProtoOAAssetListReq solicita ao backend do cTrader que devolva uma lista de todos os ativos disponíveis para negociação numa conta atualmente autorizada.

Mensagens de resposta¶

As mensagens de resposta marcam dados que são recebidos do backend do cTrader.

As mensagens de resposta são marcadas com Res no final dos seus respetivos nomes. Como ilustração, a mensagem ProtoOAAssetListRes tem um campo repetido (asset) que contém todos os ativos que a conta atualmente autorizada pode negociar.

Mensagens de evento¶

As mensagens de evento notificam assincronamente todos os seus subscritores de que um determinado evento foi acionado.

As mensagens de evento são marcadas com Event no final dos seus respetivos nomes. Por exemplo, o ProtoOAMarginChangedEvent é enviado sempre que o montante de margem alocado a uma posição específica é alterado.

Mensagens de modelo¶

As mensagens de modelo descrevem as entidades que formam o modelo de domínio no backend do cTrader.

Os nomes das mensagens de modelo terminam sempre com o nome da entidade que estão a definir. Como exemplo, a mensagem ProtoOAAsset define a entidade Asset.

Repositório de mensagens ¶

Pode transferir a versão mais recente dos ficheiros de mensagens Protocol Buffers do Open API do cTrader a partir deste repositório.

Recomendamos que siga o repositório de mensagens se quiser ser notificado sempre que uma nova versão dos ficheiros de mensagens for lançada.

Compilar mensagens Protobuf ¶

Depois de obter as mensagens Protobuf necessárias, pode executar o compilador Protobuf para a linguagem escolhida nos ficheiros .proto que definem estas mensagens. Em caso de sucesso, o compilador irá gerar classes de acesso a dados na sua linguagem preferida.

Estas classes fornecem acessores simples para cada campo (como name() e set_name()) bem como métodos para lidar com serialização e desserialização. O nome de cada classe deve corresponder ao nome completo de cada mensagem que foi compilada. Neste momento, pode utilizar livremente as classes geradas na sua aplicação para preencher, serializar e desserializar mensagens Protobuf.

Para saber mais sobre compilação de mensagens protobuf usando a linguagem da sua escolha.