Serializzazione e deserializzazione dei messaggi¶

Per serializzare e deserializzare i messaggi inviati a e dal backend di cTrader, puoi utilizzare Protocol Buffers (Protobufs) o JSON (JavaScript Object Notation).

Di seguito, definiamo in dettaglio ciascun metodo di serializzazione e deserializzazione.

JSON ¶

Gli oggetti JSON possono essere definiti come semplici coppie chiave-valore. Nota che le chiavi sono sempre stringhe mentre i valori possono essere di diversi tipi di dati come mostrato nell'esempio seguente.

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

Nell'esempio, il valore della chiave "clientMsgId" è una stringa mentre il valore della chiave "payloadType" è un intero. La chiave "payload" contiene un altro oggetto JSON che è annidato nel corpo dell'oggetto padre. Il valore della chiave "payload.keyOne" è un elenco di interi.

Scopri come puoi inviare e ricevere JSON.

Protocol Buffers ¶

Protocol Buffers (o Protobufs) offrono un meccanismo neutrale rispetto al linguaggio e alla piattaforma, estensibile per la serializzazione di dati strutturati. Utilizzando Protobufs, puoi codificare dati strutturati in un formato efficiente ma estensibile.

Con Protobufs, devi definire solo una volta come vuoi che i tuoi dati siano strutturati. Questo viene fatto specificando i tipi di messaggio Protobuf nei file .proto.

Ogni messaggio Protobuf è un record di informazioni contenente una serie di coppie nome-valore. Di seguito, puoi trovare un esempio base di un file .proto che definisce un messaggio contenente informazioni su 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;  
}

Come puoi vedere, il formato del messaggio è semplice. Ogni tipo di messaggio ha uno o più campi numerati in modo univoco, e ogni campo ha un nome e un tipo di valore, dove i tipi di valore possono essere numeri (interi o in virgola mobile), booleani, stringhe, byte grezzi o anche (come nell'esempio sopra) altri tipi di messaggio Protocol Buffer, permettendoti di strutturare i tuoi dati gerarchicamente.

Puoi trovare maggiori informazioni sulla scrittura di file .proto nella guida al linguaggio Protocol Buffer.

Scopri di più sui Protocol Buffers.

Visualizza un tutorial su invio e ricezione di Protobufs.

ProtoMessages ¶

Quando lavori con Protobufs, invierai e riceverai oggetti ProtoMessage progettati da Spotware.

Per gestire la frammentazione della rete, l'invio dei messaggi utilizza la seguente struttura di frame.

1
2
3
4

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

Ogni ProtoMessage ha la seguente struttura.

1
2
3
4
5

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

La struttura contiene due campi obbligatori.

• payloadType. Contiene l'ID ProtoPayloadType. Questo campo denota il tipo dell'oggetto Protobuf serializzato nel campo payload.
• payload. Contiene il messaggio Protobuf serializzato effettivo che corrisponde a payloadType.

Un altro campo è opzionale.

• clientMsgId. Contiene l'ID del messaggio che viene assegnato dal client.

La definizione effettiva di ProtoMessage appare come segue.

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

Convenzione di denominazione¶

I messaggi Protobuf che formano cTrader Open API possono essere categorizzati nei seguenti tipi:

• Messaggi di richiesta
• Messaggi di risposta
• Messaggi di evento
• Messaggi di modello

Messaggi di richiesta¶

I messaggi di richiesta sono utilizzati per chiedere informazioni al backend di cTrader o per eseguire varie operazioni.

I messaggi di richiesta sono contrassegnati con Req alla fine dei loro rispettivi nomi. Ad esempio, il messaggio ProtoOAAssetListReq richiede al backend di cTrader di restituire un elenco di tutti gli asset disponibili per il trading per un account attualmente autorizzato.

Messaggi di risposta¶

I messaggi di risposta indicano i dati ricevuti dal backend di cTrader.

I messaggi di risposta sono contrassegnati con Res alla fine dei loro rispettivi nomi. Come illustrazione, il messaggio ProtoOAAssetListRes ha un campo ripetuto (asset) che contiene tutti gli asset che l'account attualmente autorizzato può negoziare.

Messaggi di evento¶

I messaggi di evento notificano in modo asincrono a tutti i loro abbonati che un particolare evento è stato attivato.

I messaggi di evento sono contrassegnati con Event alla fine dei loro rispettivi nomi. Ad esempio, il ProtoOAMarginChangedEvent viene inviato ogni volta che l'importo del margine allocato a una specifica posizione viene modificato.

Messaggi di modello¶

I messaggi di modello descrivono le entità che formano il modello di dominio nel backend di cTrader.

I nomi dei messaggi di modello terminano sempre con il nome dell'entità che stanno definendo. Ad esempio, il messaggio ProtoOAAsset definisce l'entità Asset.

Repository dei messaggi ¶

Puoi scaricare l'ultima versione dei file di messaggi Protocol Buffers di cTrader Open API da questo repository.

Ti consigliamo di seguire il repository dei messaggi se desideri essere notificato ogni volta che viene rilasciata una nuova versione dei file di messaggi.

Compilare i messaggi Protobuf ¶

Una volta ottenuti i messaggi Protobuf richiesti, puoi eseguire il compilatore Protobuf per il linguaggio scelto sui file .proto che definiscono questi messaggi. In caso di successo, il compilatore genererà classi di accesso ai dati nel tuo linguaggio preferito.

Queste classi forniscono semplici accessori per ogni campo (come name() e set_name()) oltre a metodi per gestire la serializzazione e la deserializzazione. Il nome di ciascuna classe dovrebbe corrispondere al nome completo di ciascun messaggio compilato. A questo punto, puoi utilizzare liberamente le classi generate nella tua applicazione per popolare, serializzare e deserializzare i messaggi Protobuf.

Per saperne di più sulla compilazione dei messaggi protobuf utilizzando il linguaggio di tua scelta.