Serializacja i deserializacja komunikatów¶

Aby serializować i deserializować komunikaty wysyłane do i z backendu cTrader, możesz użyć Protocol Buffers (Protobufs) lub JSON (JavaScript Object Notation).

Poniżej szczegółowo definiujemy każdą metodę serializacji i deserializacji.

JSON ¶

Obiekty JSON można zdefiniować jako proste pary klucz-wartość. Należy pamiętać, że klucze są zawsze ciągami znaków, podczas gdy wartości mogą być różnych typów danych, jak pokazano w poniższym przykładzie.

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

W przykładzie wartość klucza „clientMsgId" jest ciągiem znaków, podczas gdy wartość klucza „payloadType" jest liczbą całkowitą. Klucz „payload" zawiera inny obiekt JSON, który jest zagnieżdżony w treści obiektu nadrzędnego. Wartość klucza „payload.keyOne" jest listą liczb całkowitych.

Dowiedz się, jak możesz wysyłać i odbierać JSON.

Protocol Buffers ¶

Protocol Buffers (lub Protobufs) oferują neutralny językowo i platformowo, rozszerzalny mechanizm serializacji danych strukturalnych. Używając Protobufs, możesz kodować dane strukturalne w wydajnym, a jednocześnie rozszerzalnym formacie.

Dzięki Protobufs wystarczy raz zdefiniować, jak chcesz, aby Twoje dane były ustrukturyzowane. Odbywa się to poprzez określenie typów komunikatów Protobuf w plikach .proto.

Każdy komunikat Protobuf to rekord informacji zawierający serię par nazwa-wartość. Poniżej znajdziesz podstawowy przykład pliku .proto, który definiuje komunikat zawierający informacje o osobie.

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

Jak widać, format komunikatu jest prosty. Każdy typ komunikatu ma jedno lub więcej unikalnie ponumerowanych pól, a każde pole ma nazwę i typ wartości, gdzie typy wartości mogą być liczbami (całkowitymi lub zmiennoprzecinkowymi), wartościami logicznymi, ciągami znaków, surowymi bajtami, a nawet (jak w powyższym przykładzie) innymi typami komunikatów Protocol Buffer, co pozwala na hierarchiczne strukturyzowanie danych.

Więcej informacji na temat pisania plików .proto można znaleźć w przewodniku po języku Protocol Buffer.

Dowiedz się więcej o Protocol Buffers.

Zobacz samouczek dotyczący wysyłania i odbierania Protobufs.

ProtoMessages ¶

Podczas pracy z Protobufs będziesz wysyłać i odbierać obiekty ProtoMessage zaprojektowane przez Spotware.

Aby obsłużyć fragmentację sieci, wysyłanie komunikatów wykorzystuje następującą strukturę ramki.

1
2
3
4

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

Każdy ProtoMessage ma następującą strukturę.

1
2
3
4
5

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

Struktura zawiera dwa obowiązkowe pola.

• payloadType. Zawiera identyfikator ProtoPayloadType. To pole oznacza typ obiektu Protobuf zserializowanego w polu payload.
• payload. Zawiera rzeczywisty zserializowany komunikat Protobuf, który odpowiada payloadType.

Jedno inne pole jest opcjonalne.

• clientMsgId. Zawiera identyfikator komunikatu, który jest przypisywany przez klienta.

Rzeczywista definicja ProtoMessage wygląda następująco.

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

Konwencja nazewnictwa¶

Komunikaty Protobuf, które tworzą cTrader Open API, można podzielić na następujące typy:

• Komunikaty żądań
• Komunikaty odpowiedzi
• Komunikaty zdarzeń
• Komunikaty modeli

Komunikaty żądań¶

Komunikaty żądań są używane do żądania informacji od backendu cTradera lub wykonywania różnych operacji.

Komunikaty żądań są oznaczone Req na końcu ich odpowiednich nazw. Na przykład komunikat ProtoOAAssetListReq żąda od backendu cTradera zwrócenia listy wszystkich aktywów dostępnych do handlu dla aktualnie autoryzowanego konta.

Komunikaty odpowiedzi¶

Komunikaty odpowiedzi oznaczają dane, które są odbierane z backendu cTradera.

Komunikaty odpowiedzi są oznaczone Res na końcu ich odpowiednich nazw. Dla przykładu komunikat ProtoOAAssetListRes ma powtarzające się pole (asset), które zawiera wszystkie aktywa, którymi może handlować aktualnie autoryzowane konto.

Komunikaty zdarzeń¶

Komunikaty zdarzeń asynchronicznie powiadamiają wszystkich swoich subskrybentów, że określone zdarzenie zostało wywołane.

Komunikaty zdarzeń są oznaczone Event na końcu ich odpowiednich nazw. Na przykład ProtoOAMarginChangedEvent jest wysyłany za każdym razem, gdy zmienia się kwota depozytu zabezpieczającego przydzielonego do określonej pozycji.

Komunikaty modeli¶

Komunikaty modeli opisują jednostki, które tworzą model domeny w backendzie cTradera.

Nazwy komunikatów modeli zawsze kończą się nazwą jednostki, którą definiują. Dla przykładu komunikat ProtoOAAsset definiuje jednostkę Asset.

Repozytorium komunikatów ¶

Możesz pobrać najnowszą wersję plików komunikatów Protocol Buffers cTrader Open API z tego repozytorium.

Zalecamy śledzenie repozytorium komunikatów, jeśli chcesz otrzymywać powiadomienia o wydaniu nowej wersji plików komunikatów.

Kompiluj komunikaty Protobuf ¶

Po uzyskaniu wymaganych komunikatów Protobuf możesz uruchomić kompilator Protobuf dla wybranego języka na plikach .proto definiujących te komunikaty. W przypadku powodzenia kompilator wygeneruje klasy dostępu do danych w preferowanym języku.

Te klasy zapewniają proste akcesory dla każdego pola (takie jak name() i set_name()), a także metody obsługi serializacji i deserializacji. Nazwa każdej klasy powinna odpowiadać pełnej nazwie każdego skompilowanego komunikatu. W tym momencie możesz swobodnie używać wygenerowanych klas w swojej aplikacji do wypełniania, serializacji i deserializacji komunikatów Protobuf.

Aby dowiedzieć się więcej o kompilowaniu komunikatów protobuf przy użyciu wybranego języka.