Serialisasi dan deserialisasi pesan¶

Untuk melakukan serialisasi dan deserialisasi pesan yang dikirim ke dan dari backend cTrader, Anda dapat menggunakan Protocol Buffers (Protobufs) atau JSON (JavaScript Object Notation).

Di bawah ini, kami mendefinisikan setiap metode serialisasi dan deserialisasi secara detail.

JSON ¶

Objek JSON dapat didefinisikan sebagai pasangan kunci-nilai sederhana. Perhatikan bahwa kunci selalu berupa string sementara nilai dapat berupa tipe data yang berbeda seperti yang ditunjukkan dalam contoh di bawah ini.

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

Dalam contoh, nilai dari kunci "clientMsgId" adalah string sementara nilai dari kunci "payloadType" adalah integer. Kunci "payload" berisi objek JSON lain yang bersarang di dalam tubuh objek induk. Nilai dari kunci "payload.keyOne" adalah daftar integer.

Pelajari cara Anda dapat mengirim dan menerima JSON.

Protocol Buffers ¶

Protocol Buffers (atau Protobufs) menawarkan mekanisme yang netral terhadap bahasa dan platform, serta dapat diperluas untuk melakukan serialisasi data terstruktur. Dengan menggunakan Protobufs, Anda dapat mengkodekan data terstruktur dalam format yang efisien namun dapat diperluas.

Dengan Protobufs, Anda hanya perlu mendefinisikan bagaimana Anda ingin data Anda terstruktur sekali. Ini dilakukan dengan menentukan jenis pesan Protobuf dalam file .proto.

Setiap pesan Protobuf adalah catatan informasi yang berisi serangkaian pasangan nama-nilai. Di bawah ini, Anda dapat menemukan contoh dasar file .proto yang mendefinisikan pesan yang berisi informasi tentang seseorang.

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

Seperti yang Anda lihat, format pesan sederhana. Setiap jenis pesan memiliki satu atau lebih bidang yang diberi nomor unik, dan setiap bidang memiliki nama dan tipe nilai, di mana tipe nilai dapat berupa angka (integer atau floating-point), boolean, string, byte mentah, atau bahkan (seperti dalam contoh di atas) jenis pesan Protocol Buffer lainnya, memungkinkan Anda untuk menyusun data Anda secara hierarkis.

Anda dapat menemukan informasi lebih lanjut tentang menulis file .proto di panduan bahasa Protocol Buffer.

Pelajari lebih lanjut tentang Protocol Buffers.

Lihat tutorial tentang mengirim dan menerima Protobufs.

ProtoMessages ¶

Saat bekerja dengan Protobufs, Anda akan mengirim dan menerima objek ProtoMessage yang dirancang oleh Spotware.

Untuk menangani fragmentasi jaringan, pengiriman pesan menggunakan struktur frame berikut.

1
2
3
4

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

Setiap ProtoMessage memiliki struktur berikut.

1
2
3
4
5

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

Struktur ini berisi dua bidang wajib.

• payloadType. Berisi ID ProtoPayloadType. Bidang ini menunjukkan jenis objek Protobuf yang diserialisasi di bidang payload.
• payload. Berisi pesan Protobuf yang sebenarnya yang diserialisasi yang sesuai dengan payloadType.

Satu bidang lainnya bersifat opsional.

• clientMsgId. Berisi ID pesan yang ditetapkan oleh klien.

Definisi ProtoMessage yang sebenarnya terlihat sebagai berikut.

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

Konvensi penamaan¶

Pesan Protobuf yang membentuk cTrader Open API dapat dikategorikan ke dalam jenis berikut:

• Pesan permintaan
• Pesan respons
• Pesan acara
• Pesan model

Pesan permintaan¶

Pesan permintaan digunakan untuk meminta informasi dari backend cTrader atau melakukan berbagai operasi.

Pesan permintaan ditandai dengan Req di akhir nama masing-masing. Sebagai contoh, pesan ProtoOAAssetListReq meminta backend cTrader untuk mengembalikan daftar semua aset yang tersedia untuk trading ke akun yang saat ini diotorisasi.

Pesan respons¶

Pesan respons menandai data yang diterima dari backend cTrader.

Pesan respons ditandai dengan Res di akhir nama masing-masing. Sebagai ilustrasi, pesan ProtoOAAssetListRes memiliki bidang berulang (asset) yang berisi semua aset yang dapat diperdagangkan oleh akun yang saat ini diotorisasi.

Pesan acara¶

Pesan acara secara asinkron memberi tahu semua pelanggannya bahwa suatu acara tertentu telah dipicu.

Pesan acara ditandai dengan Event di akhir nama masing-masing. Misalnya, ProtoOAMarginChangedEvent dikirim setiap kali jumlah margin yang dialokasikan ke posisi tertentu diubah.

Pesan model¶

Pesan model mendeskripsikan entitas yang membentuk model domain di backend cTrader.

Nama pesan model selalu diakhiri dengan nama entitas yang mereka definisikan. Sebagai contoh, pesan ProtoOAAsset mendefinisikan entitas Asset.

Repositori pesan ¶

Anda dapat mengunduh versi terbaru file pesan Protobuf Open API cTrader dari repositori ini.

Kami merekomendasikan Anda mengikuti repositori pesan jika Anda ingin mendapatkan pemberitahuan setiap kali versi baru file pesan dirilis.

Kompilasi pesan Protobuf ¶

Setelah Anda mendapatkan pesan Protobuf yang diperlukan, Anda dapat menjalankan kompiler Protobuf untuk bahasa pilihan Anda pada file .proto yang mendefinisikan pesan-pesan ini. Jika berhasil, kompiler akan menghasilkan kelas akses data dalam bahasa pilihan Anda.

Kelas-kelas ini menyediakan pengakses sederhana untuk setiap bidang (seperti name() dan set_name()) serta metode untuk menangani serialisasi dan deserialisasi. Nama setiap kelas harus sesuai dengan nama lengkap setiap pesan yang dikompilasi. Pada titik ini, Anda dapat dengan bebas menggunakan kelas yang dihasilkan dalam aplikasi Anda untuk mengisi, menserialisasi, dan mendeserialisasi pesan Protobuf.

Untuk mempelajari lebih lanjut tentang mengkompilasi pesan protobuf menggunakan bahasa pilihan Anda.