Serialización y deserialización de mensajes¶

Para serializar y deserializar mensajes enviados hacia y desde el backend de cTrader, puede usar Protocol Buffers (Protobufs) o JSON (JavaScript Object Notation).

A continuación, definimos cada método de serialización y deserialización en detalle.

JSON ¶

Los objetos JSON se pueden definir como simples pares clave-valor. Tenga en cuenta que las claves siempre son cadenas mientras que los valores pueden ser de diferentes tipos de datos como se muestra en el ejemplo a continuación.

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

En el ejemplo, el valor de la clave "clientMsgId" es una cadena mientras que el valor de la clave "payloadType" es un entero. La clave "payload" contiene otro objeto JSON que está anidado en el cuerpo del objeto padre. El valor de la clave "payload.keyOne" es una lista de enteros.

Aprenda cómo enviar y recibir JSON.

Protocol Buffers ¶

Protocol Buffers (o Protobufs) ofrecen un mecanismo neutral en cuanto a lenguaje y plataforma, extensible para serializar datos estructurados. Al usar Protobufs, puede codificar datos estructurados en un formato eficiente pero extensible.

Con Protobufs, solo necesita definir una vez cómo desea que se estructuren sus datos. Esto se hace especificando tipos de mensajes Protobuf en archivos .proto.

Cada mensaje Protobuf es un registro de información que contiene una serie de pares nombre-valor. A continuación, puede encontrar un ejemplo básico de un archivo .proto que define un mensaje que contiene información sobre una persona.

 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 puede ver, el formato del mensaje es simple. Cada tipo de mensaje tiene uno o más campos numerados de forma única, y cada campo tiene un nombre y un tipo de valor, donde los tipos de valor pueden ser números (enteros o de punto flotante), booleanos, cadenas, bytes sin procesar o incluso (como en el ejemplo anterior) otros tipos de mensajes de Protocol Buffer, lo que le permite estructurar sus datos jerárquicamente.

Puede encontrar más información sobre cómo escribir archivos .proto en la guía del lenguaje Protocol Buffer.

Aprenda más sobre Protocol Buffers.

Ver un tutorial sobre envío y recepción de Protobufs.

ProtoMessages ¶

Cuando trabaje con Protobufs, estará enviando y recibiendo objetos ProtoMessage diseñados por Spotware.

Para manejar la fragmentación de red, el envío de mensajes utiliza la siguiente estructura de marco.

1
2
3
4

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

Cada ProtoMessage tiene la siguiente estructura.

1
2
3
4
5

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

La estructura contiene dos campos obligatorios.

• payloadType. Contiene el ID de ProtoPayloadType. Este campo denota el tipo del objeto Protobuf serializado en el campo payload.
• payload. Contiene el mensaje Protobuf serializado real que corresponde a payloadType.

Otro campo es opcional.

• clientMsgId. Contiene el ID del mensaje que es asignado por el cliente.

La definición real de ProtoMessage es la siguiente.

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.  
}

Convención de nomenclatura¶

Los mensajes Protobuf que forman la Open API de cTrader se pueden categorizar en los siguientes tipos:

• Mensajes de solicitud
• Mensajes de respuesta
• Mensajes de eventos
• Mensajes de modelo

Mensajes de solicitud¶

Los mensajes de solicitud se utilizan para solicitar información al backend de cTrader o realizar varias operaciones.

Los mensajes de solicitud están marcados con Req al final de sus respectivos nombres. Por ejemplo, el mensaje ProtoOAAssetListReq solicita al backend de cTrader que devuelva una lista de todos los activos disponibles para operar en una cuenta actualmente autorizada.

Mensajes de respuesta¶

Los mensajes de respuesta marcan los datos que se reciben del backend de cTrader.

Los mensajes de respuesta están marcados con Res al final de sus respectivos nombres. Como ilustración, el mensaje ProtoOAAssetListRes tiene un campo repetido (asset) que contiene todos los activos con los que la cuenta actualmente autorizada puede operar.

Mensajes de eventos¶

Los mensajes de eventos notifican de forma asíncrona a todos sus suscriptores que se ha activado un evento particular.

Los mensajes de eventos están marcados con Event al final de sus respectivos nombres. Por ejemplo, el ProtoOAMarginChangedEvent se envía cada vez que cambia la cantidad de margen asignado a una posición específica.

Mensajes de modelo¶

Los mensajes de modelo describen las entidades que forman el modelo de dominio en el backend de cTrader.

Los nombres de los mensajes de modelo siempre terminan con el nombre de la entidad que están definiendo. Como ejemplo, el mensaje ProtoOAAsset define la entidad Asset.

Repositorio de mensajes ¶

Puede descargar la última versión de los archivos de mensajes Protocol Buffers de la Open API de cTrader desde este repositorio.

Le recomendamos seguir el repositorio de mensajes si desea recibir notificaciones cada vez que se publique una nueva versión de los archivos de mensajes.

Compilar mensajes Protobuf ¶

Una vez que obtenga los mensajes Protobuf requeridos, puede ejecutar el compilador Protobuf para su lenguaje elegido en los archivos .proto que definen estos mensajes. Si tiene éxito, el compilador generará clases de acceso a datos en su lenguaje preferido.

Estas clases proporcionan accesores simples para cada campo (como name() y set_name()) así como métodos para manejar la serialización y deserialización. El nombre de cada clase debe coincidir con el nombre completo de cada mensaje que fue compilado. En este punto, puede usar libremente las clases generadas en su aplicación para poblar, serializar y deserializar mensajes Protobuf.

Para aprender más sobre la compilación de mensajes protobuf usando el lenguaje de su elección.