Menyirikan dan menyahserikan mesej¶

Untuk menyirikan dan menyahserikan mesej yang dihantar ke dan dari backend cTrader, anda boleh menggunakan sama ada Protocol Buffers (Protobufs) atau JSON (JavaScript Object Notation).

Di bawah, kami mentakrifkan setiap kaedah penyirian dan penyahserian secara terperinci.

JSON ¶

Objek JSON boleh ditakrifkan sebagai pasangan kunci-nilai mudah. Perhatikan bahawa kunci sentiasa rentetan manakala nilai boleh terdiri daripada jenis data yang berbeza seperti yang ditunjukkan dalam contoh di bawah.

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

Dalam contoh, nilai kunci "clientMsgId" adalah rentetan manakala nilai kunci "payloadType" adalah integer. Kunci "payload" mengandungi objek JSON lain yang disarangkan dalam badan objek induk. Nilai kunci "payload.keyOne" adalah senarai integer.

Ketahui cara anda boleh menghantar dan menerima JSON.

Protocol Buffers ¶

Protocol Buffers (atau Protobufs) menawarkan mekanisme neutral bahasa dan platform, boleh diperluas untuk menyirikan data berstruktur. Dengan menggunakan Protobufs, anda boleh menyulitkan data berstruktur dalam format yang cekap namun boleh diperluas.

Dengan Protobufs, anda hanya perlu mentakrifkan cara anda mahu data anda berstruktur sekali. Ini dilakukan dengan menentukan jenis mesej Protobuf dalam fail .proto.

Setiap mesej Protobuf adalah rekod maklumat yang mengandungi siri pasangan nama-nilai. Di bawah, anda boleh menemui contoh asas fail .proto yang mentakrifkan mesej yang mengandungi maklumat 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 mesej adalah mudah. Setiap jenis mesej mempunyai satu atau lebih medan bernombor unik, dan setiap medan mempunyai nama dan jenis nilai, di mana jenis nilai boleh menjadi nombor (integer atau titik terapung), boolean, rentetan, bait mentah atau bahkan (seperti dalam contoh di atas) jenis mesej Protocol Buffer lain, membolehkan anda menyusun data anda secara hierarki.

Anda boleh menemui lebih banyak maklumat tentang menulis fail .proto dalam panduan bahasa Protocol Buffer.

Ketahui lebih lanjut tentang Protocol Buffers.

Lihat tutorial tentang menghantar dan menerima Protobufs.

ProtoMessages ¶

Apabila bekerja dengan Protobufs, anda akan menghantar dan menerima objek ProtoMessage yang direka oleh Spotware.

Untuk mengendalikan fragmentasi rangkaian, penghantaran mesej menggunakan struktur bingkai berikut.

1
2
3
4

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

Setiap ProtoMessage mempunyai struktur berikut.

1
2
3
4
5

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

Struktur mengandungi dua medan wajib.

• payloadType. Mengandungi ID ProtoPayloadType. Medan ini menandakan jenis objek Protobuf yang disirikan dalam medan payload.
• payload. Mengandungi mesej Protobuf yang disirikan sebenar yang sepadan dengan payloadType.

Satu medan lain adalah pilihan.

• clientMsgId. Mengandungi ID mesej yang ditetapkan oleh klien.

Takrifan ProtoMessage sebenar kelihatan seperti 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.  
}

Konvensyen penamaan¶

Mesej Protobuf yang membentuk cTrader Open API boleh dikategorikan kepada jenis berikut:

• Mesej permintaan
• Mesej respons
• Mesej peristiwa
• Mesej model

Mesej permintaan¶

Mesej permintaan digunakan untuk meminta maklumat daripada sistem bahagian belakang cTrader atau melakukan pelbagai operasi.

Mesej permintaan ditandakan dengan Req pada akhir nama masing-masing. Sebagai contoh, mesej ProtoOAAssetListReq meminta sistem bahagian belakang cTrader untuk mengembalikan senarai semua aset yang tersedia untuk didagangkan kepada akaun yang sedang diberi kuasa.

Mesej respons¶

Mesej respons menandakan data yang diterima daripada sistem bahagian belakang cTrader.

Mesej respons ditandakan dengan Res pada akhir nama masing-masing. Sebagai ilustrasi, mesej ProtoOAAssetListRes mempunyai medan berulang (asset) yang mengandungi semua aset yang boleh didagangkan oleh akaun yang sedang diberi kuasa.

Mesej peristiwa¶

Mesej peristiwa secara asinkron memberitahu semua pelanggan mereka bahawa peristiwa tertentu telah dicetuskan.

Mesej peristiwa ditandakan dengan Event pada akhir nama masing-masing. Sebagai contoh, ProtoOAMarginChangedEvent dihantar setiap kali jumlah margin yang diperuntukkan kepada kedudukan tertentu berubah.

Mesej model¶

Mesej model menerangkan entiti yang membentuk model domain dalam sistem bahagian belakang cTrader.

Nama mesej model selalu berakhir dengan nama entiti yang mereka takrifkan. Sebagai contoh, mesej ProtoOAAsset mentakrifkan entiti Asset.

Repositori mesej ¶

Anda boleh memuat turun versi terkini fail mesej Protobuf Open API cTrader dari repositori ini.

Kami mengesyorkan anda mengikuti repositori mesej jika anda ingin dimaklumkan setiap kali versi baharu fail mesej dikeluarkan.

Kompilasi mesej Protobuf ¶

Setelah anda memperoleh mesej Protobuf yang diperlukan, anda boleh menjalankan pengkompil Protobuf untuk bahasa pilihan anda pada fail .proto yang mentakrifkan mesej ini. Pada kejayaan, pengkompil akan menjana kelas akses data dalam bahasa pilihan anda.

Kelas ini menyediakan pengakses mudah untuk setiap medan (seperti name() dan set_name()) serta kaedah untuk mengendalikan penyiratan dan penyahseratan. Nama setiap kelas harus sepadan dengan nama penuh setiap mesej yang dikompil. Pada ketika ini, anda boleh menggunakan kelas yang dijana secara bebas dalam aplikasi anda untuk mengisi, menyiratan dan menyahseratan mesej Protobuf.

Untuk mengetahui lebih lanjut tentang mengkompilasi mesej protobuf menggunakan bahasa pilihan anda.