Sérialisation et désérialisation des messages¶

Pour sérialiser et désérialiser les messages envoyés et reçus du backend de cTrader, vous pouvez utiliser soit Protocol Buffers (Protobufs) soit JSON (JavaScript Object Notation).

Ci-dessous, nous définissons en détail chaque méthode de sérialisation et de désérialisation.

JSON ¶

Les objets JSON peuvent être définis comme de simples paires clé-valeur. Notez que les clés sont toujours des chaînes de caractères tandis que les valeurs peuvent être de différents types de données comme montré dans l'exemple ci-dessous.

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

Dans l'exemple, la valeur de la clé "clientMsgId" est une chaîne de caractères tandis que la valeur de la clé "payloadType" est un entier. La clé "payload" contient un autre objet JSON qui est imbriqué dans le corps de l'objet parent. La valeur de la clé "payload.keyOne" est une liste d'entiers.

Apprenez comment vous pouvez envoyer et recevoir du JSON.

Protocol Buffers ¶

Protocol Buffers (ou Protobufs) offrent un mécanisme neutre en termes de langage et de plateforme, extensible pour la sérialisation de données structurées. En utilisant Protobufs, vous pouvez encoder des données structurées dans un format efficace mais extensible.

Avec Protobufs, vous n'avez besoin de définir qu'une seule fois la façon dont vous voulez que vos données soient structurées. Cela se fait en spécifiant les types de messages Protobuf dans des fichiers .proto.

Chaque message Protobuf est un enregistrement d'informations contenant une série de paires nom-valeur. Ci-dessous, vous trouverez un exemple basique d'un fichier .proto qui définit un message contenant des informations sur une personne.

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

Comme vous pouvez le voir, le format du message est simple. Chaque type de message a un ou plusieurs champs numérotés de manière unique, et chaque champ a un nom et un type de valeur, où les types de valeurs peuvent être des nombres (entiers ou à virgule flottante), des booléens, des chaînes de caractères, des octets bruts ou même (comme dans l'exemple ci-dessus) d'autres types de messages Protocol Buffer, vous permettant de structurer vos données de manière hiérarchique.

Vous pouvez trouver plus d'informations sur l'écriture de fichiers .proto dans le guide du langage Protocol Buffer.

En savoir plus sur les Protocol Buffers.

Consultez un tutoriel sur l'envoi et la réception de Protobufs.

ProtoMessages ¶

Lorsque vous travaillez avec des Protobufs, vous enverrez et recevrez des objets ProtoMessage conçus par Spotware.

Pour gérer la fragmentation du réseau, l'envoi de messages utilise la structure de trame suivante.

1
2
3
4

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

Chaque ProtoMessage a la structure suivante.

1
2
3
4
5

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

La structure contient deux champs obligatoires.

• payloadType. Contient l'ID ProtoPayloadType. Ce champ indique le type de l'objet Protobuf sérialisé dans le champ payload.
• payload. Contient le message Protobuf sérialisé réel qui correspond à payloadType.

Un autre champ est optionnel.

• clientMsgId. Contient l'ID du message qui est attribué par le client.

La définition réelle de ProtoMessage se présente comme suit.

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

Convention de nommage¶

Les messages Protobuf qui forment l'Open API de cTrader peuvent être catégorisés dans les types suivants :

• Messages de requête
• Messages de réponse
• Messages d'événement
• Messages de modèle

Messages de requête¶

Les messages de requête sont utilisés pour demander des informations au backend de cTrader ou effectuer diverses opérations.

Les messages de requête sont marqués avec Req à la fin de leurs noms respectifs. Par exemple, le message ProtoOAAssetListReq demande au backend de cTrader de renvoyer une liste de tous les actifs disponibles pour le trading pour un compte actuellement autorisé.

Messages de réponse¶

Les messages de réponse marquent les données reçues du backend de cTrader.

Les messages de réponse sont marqués avec Res à la fin de leurs noms respectifs. À titre d'illustration, le message ProtoOAAssetListRes a un champ répété (asset) qui contient tous les actifs que le compte actuellement autorisé peut trader.

Messages d'événement¶

Les messages d'événement notifient de manière asynchrone tous leurs abonnés qu'un événement particulier a été déclenché.

Les messages d'événement sont marqués avec Event à la fin de leurs noms respectifs. Par exemple, le ProtoOAMarginChangedEvent est envoyé chaque fois que le montant de la marge allouée à une position spécifique est modifié.

Messages de modèle¶

Les messages de modèle décrivent les entités qui forment le modèle de domaine dans le backend de cTrader.

Les noms des messages de modèle se terminent toujours par le nom de l'entité qu'ils définissent. Par exemple, le message ProtoOAAsset définit l'entité Asset.

Dépôt de messages ¶

Vous pouvez télécharger la dernière version des fichiers de messages Protocol Buffers de l'Open API de cTrader depuis ce dépôt.

Nous vous recommandons de suivre le dépôt de messages si vous souhaitez être notifié chaque fois qu'une nouvelle version des fichiers de messages est publiée.

Compiler les messages Protobuf ¶

Une fois que vous avez obtenu les messages Protobuf requis, vous pouvez exécuter le compilateur Protobuf pour votre langage choisi sur les fichiers .proto définissant ces messages. En cas de succès, le compilateur générera des classes d'accès aux données dans votre langage préféré.

Ces classes fournissent des accesseurs simples pour chaque champ (tels que name() et set_name()) ainsi que des méthodes pour gérer la sérialisation et la désérialisation. Le nom de chaque classe doit correspondre au nom complet de chaque message qui a été compilé. À ce stade, vous pouvez librement utiliser les classes générées dans votre application pour remplir, sérialiser et désérialiser les messages Protobuf.

Pour en savoir plus sur la compilation des messages protobuf en utilisant le langage de votre choix.