การซีเรียลไลเซชันและดีซีเรียลไลเซชันข้อความ¶

เพื่อซีเรียลไลเซชันและดีซีเรียลไลเซชันข้อความที่ส่งไปและมาจากแบ็กเอนด์ของ cTrader คุณสามารถใช้ทั้ง Protocol Buffers (Protobufs) หรือ JSON (JavaScript Object Notation)

ด้านล่าง เรากำหนดแต่ละวิธีการซีเรียลไลเซชันและดีซีเรียลไลเซชันอย่างละเอียด

JSON ¶

ออบเจ็กต์ JSON สามารถกำหนดเป็นคู่คีย์-ค่าที่เรียบง่าย โปรดทราบว่าคีย์เป็นสตริงเสมอในขณะที่ค่าสามารถเป็นประเภทข้อมูลที่แตกต่างกันได้ ดังตัวอย่างด้านล่าง

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

ในตัวอย่าง ค่าของคีย์ "clientMsgId" เป็นสตริงในขณะที่ค่าของคีย์ "payloadType" เป็นจำนวนเต็ม คีย์ "payload" มีออบเจ็กต์ JSON อื่นที่ซ้อนอยู่ในเนื้อหาของออบเจ็กต์หลัก ค่าของคีย์ "payload.keyOne" เป็นรายการของจำนวนเต็ม

เรียนรู้วิธีที่คุณสามารถ ส่งและรับ JSON

Protocol Buffers ¶

Protocol Buffers (หรือ Protobufs) เสนอกลไกที่เป็นกลางต่อภาษาและแพลตฟอร์ม และสามารถขยายได้สำหรับการซีเรียลไลเซชันข้อมูลที่มีโครงสร้าง โดยการใช้ Protobufs คุณสามารถเข้ารหัสข้อมูลที่มีโครงสร้างในรูปแบบที่มีประสิทธิภาพและสามารถขยายได้

ด้วย Protobufs คุณเพียงแค่ต้องกำหนดวิธีที่คุณต้องการให้ข้อมูลของคุณมีโครงสร้างเพียงครั้งเดียว สิ่งนี้ทำได้โดยการระบุประเภทข้อความ Protobuf ในไฟล์ .proto

แต่ละข้อความ Protobuf เป็นบันทึกข้อมูลที่มีชุดของคู่ชื่อ-ค่า ด้านล่าง คุณสามารถพบตัวอย่างพื้นฐานของไฟล์ .proto ที่กำหนดข้อความที่มีข้อมูลเกี่ยวกับบุคคล

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

ดังที่คุณเห็น รูปแบบข้อความนั้นเรียบง่าย แต่ละประเภทข้อความมีหนึ่งหรือหลายฟิลด์ที่มีหมายเลขเฉพาะ และแต่ละฟิลด์มีชื่อและประเภทค่า โดยที่ประเภทค่าสามารถเป็นตัวเลข (จำนวนเต็มหรือทศนิยม) บูลีน สตริง ไบต์ดิบ หรือแม้แต่ (ดังตัวอย่างด้านบน) ประเภทข้อความ Protocol Buffer อื่นๆ ซึ่งช่วยให้คุณสามารถจัดโครงสร้างข้อมูลของคุณแบบลำดับชั้นได้

คุณสามารถค้นหาข้อมูลเพิ่มเติมเกี่ยวกับการเขียนไฟล์ .proto ใน คู่มือภาษา Protocol Buffer

เรียนรู้เพิ่มเติมเกี่ยวกับ Protocol Buffers

ดูบทเรียนเกี่ยวกับ การส่งและรับ Protobufs

ProtoMessages ¶

เมื่อทำงานกับ Protobufs คุณจะส่งและรับออบเจ็กต์ ProtoMessage ที่ออกแบบโดย Spotware

เพื่อจัดการกับการแบ่งส่วนของเครือข่าย การส่งข้อความใช้โครงสร้างเฟรมต่อไปนี้

1
2
3
4

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

แต่ละ ProtoMessage มีโครงสร้างต่อไปนี้

1
2
3
4
5

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

โครงสร้างมีสองฟิลด์บังคับ

• payloadType. มี ID ProtoPayloadType ฟิลด์นี้ระบุประเภทของออบเจ็กต์ Protobuf ที่ถูกซีเรียลไลเซชันในฟิลด์ payload
• payload. มีข้อความ Protobuf ที่ถูกซีเรียลไลเซชันจริงที่สอดคล้องกับ payloadType

ฟิลด์อื่นหนึ่งฟิลด์เป็นทางเลือก

• clientMsgId. มี ID ข้อความที่กำหนดโดยไคลเอ็นต์

คำนิยาม ProtoMessage จริงมีลักษณะดังนี้

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

การตั้งชื่อ¶

ข้อความ Protobuf ที่ประกอบเป็น cTrader Open API สามารถแบ่งออกเป็นประเภทต่าง ๆ ดังนี้:

• ข้อความคำขอ
• ข้อความตอบกลับ
• ข้อความเหตุการณ์
• ข้อความโมเดล

ข้อความคำขอ¶

ข้อความคำขอใช้เพื่อขอข้อมูลจาก cTrader backend หรือดำเนินการต่าง ๆ

ข้อความคำขอจะถูกทำเครื่องหมายด้วย Req ที่ท้ายชื่อของแต่ละข้อความ ตัวอย่างเช่น ข้อความ ProtoOAAssetListReq ขอให้ cTrader backend ส่งกลับรายการสินทรัพย์ทั้งหมดที่สามารถเทรดได้สำหรับบัญชีที่ได้รับอนุญาตในปัจจุบัน

ข้อความตอบกลับ¶

ข้อความตอบกลับแสดงข้อมูลที่ได้รับจาก cTrader backend

ข้อความตอบกลับจะถูกทำเครื่องหมายด้วย Res ที่ท้ายชื่อของแต่ละข้อความ ตัวอย่างเช่น ข้อความ ProtoOAAssetListRes มีฟิลด์ที่ซ้ำกัน (asset) ซึ่งประกอบด้วยสินทรัพย์ทั้งหมดที่บัญชีที่ได้รับอนุญาตในปัจจุบันสามารถเทรดได้

ข้อความเหตุการณ์¶

ข้อความเหตุการณ์แจ้งเตือนผู้สมัครสมาชิกทั้งหมดแบบอะซิงโครนัสว่าเหตุการณ์เฉพาะได้ถูกกระตุ้น

ข้อความเหตุการณ์จะถูกทำเครื่องหมายด้วย Event ที่ท้ายชื่อของแต่ละข้อความ ตัวอย่างเช่น ข้อความ ProtoOAMarginChangedEvent จะถูกส่งทุกครั้งที่จำนวนมาร์จิ้นที่จัดสรรให้กับตำแหน่งเฉพาะมีการเปลี่ยนแปลง

ข้อความโมเดล¶

ข้อความโมเดลอธิบายเอนทิตีที่ประกอบเป็นโมเดลโดเมนใน cTrader backend

ชื่อของข้อความโมเดลจะลงท้ายด้วยชื่อของเอนทิตีที่กำลังกำหนด ตัวอย่างเช่น ข้อความ ProtoOAAsset กำหนดเอนทิตี Asset

คลังข้อความ ¶

คุณสามารถดาวน์โหลดไฟล์ข้อความ Protocol Buffers ล่าสุดของ cTrader Open API จาก คลังนี้

เราขอแนะนำให้คุณติดตามคลังข้อความหากคุณต้องการรับการแจ้งเตือนทุกครั้งที่มีการปล่อยเวอร์ชันใหม่ของไฟล์ข้อความ

คอมไพล์ข้อความ Protobuf ¶

เมื่อคุณได้รับข้อความ Protobuf ที่ต้องการแล้ว คุณสามารถรันคอมไพเลอร์ Protobuf สำหรับภาษาที่คุณเลือกบนไฟล์ .proto ที่กำหนดข้อความเหล่านี้ เมื่อสำเร็จ คอมไพเลอร์จะสร้างคลาสการเข้าถึงข้อมูลในภาษาที่คุณต้องการ

คลาสเหล่านี้ให้วิธีการเข้าถึงอย่างง่ายสำหรับแต่ละฟิลด์ (เช่น name() และ set_name()) รวมถึงวิธีการจัดการการซีเรียไลเซชันและดีซีเรียไลเซชัน ชื่อของแต่ละคลาสควรตรงกับชื่อเต็มของแต่ละข้อความที่ถูกคอมไพล์ ณ จุดนี้ คุณสามารถใช้คลาสที่สร้างขึ้นในแอปพลิเคชันของคุณได้อย่างอิสระเพื่อเติมข้อมูล ซีเรียไลซ์ และดีซีเรียไลซ์ข้อความ Protobuf

เรียนรู้เพิ่มเติมเกี่ยวกับ การคอมไพล์ข้อความ protobuf โดยใช้ภาษาที่คุณเลือก