Tuần tự hóa và giải tuần tự hóa tin nhắn¶

Để tuần tự hóa và giải tuần tự hóa tin nhắn được gửi đến và từ backend của cTrader, bạn có thể sử dụng Protocol Buffers (Protobufs) hoặc JSON (JavaScript Object Notation).

Bên dưới, chúng tôi định nghĩa chi tiết từng phương thức chuyển đổi và giải mã.

JSON ¶

Các đối tượng JSON có thể được định nghĩa là các cặp khóa-giá trị đơn giản. Lưu ý rằng các khóa luôn là chuỗi trong khi các giá trị có thể thuộc các kiểu dữ liệu khác nhau như được hiển thị trong ví dụ bên dưới.

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

Trong ví dụ, giá trị của khóa "clientMsgId" là một chuỗi trong khi giá trị của khóa "payloadType" là một số nguyên. Khóa "payload" chứa một đối tượng JSON khác được lồng trong phần thân của đối tượng cha. Giá trị của khóa "payload.keyOne" là một danh sách các số nguyên.

Tìm hiểu cách bạn có thể gửi và nhận JSON.

Protocol Buffers ¶

Protocol Buffers (hoặc Protobufs) cung cấp một cơ chế trung lập về ngôn ngữ và nền tảng, có thể mở rộng để chuyển đổi dữ liệu có cấu trúc. Bằng cách sử dụng Protobufs, bạn có thể mã hóa dữ liệu có cấu trúc ở một định dạng hiệu quả nhưng có thể mở rộng.

Với Protobufs, bạn chỉ cần định nghĩa cách bạn muốn cấu trúc dữ liệu của mình một lần. Điều này được thực hiện bằng cách chỉ định các kiểu thông điệp Protobuf trong các tệp .proto.

Mỗi thông điệp Protobuf là một bản ghi thông tin chứa một chuỗi các cặp tên-giá trị. Bên dưới, bạn có thể tìm thấy một ví dụ cơ bản về một tệp .proto định nghĩa một thông điệp chứa thông tin về một người.

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

Như bạn có thể thấy, định dạng thông điệp rất đơn giản. Mỗi kiểu thông điệp có một hoặc nhiều trường được đánh số duy nhất, và mỗi trường có một tên và một kiểu giá trị, trong đó kiểu giá trị có thể là số (nguyên hoặc dấu phẩy động), boolean, chuỗi, byte thô hoặc thậm chí (như trong ví dụ trên) các kiểu thông điệp Protocol Buffer khác, cho phép bạn cấu trúc dữ liệu của mình một cách phân cấp.

Bạn có thể tìm thêm thông tin về việc viết các tệp .proto trong hướng dẫn ngôn ngữ Protocol Buffer.

Tìm hiểu thêm về Protocol Buffers.

Xem hướng dẫn về gửi và nhận Protobufs.

ProtoMessages ¶

Khi làm việc với Protobufs, bạn sẽ gửi và nhận các đối tượng ProtoMessage được thiết kế bởi Spotware.

Để xử lý phân mảnh mạng, việc gửi thông điệp sử dụng cấu trúc khung sau.

1
2
3
4

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

Mỗi ProtoMessage có cấu trúc sau.

1
2
3
4
5

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

Cấu trúc chứa hai trường bắt buộc.

• payloadType. Chứa ID ProtoPayloadType. Trường này biểu thị kiểu của đối tượng Protobuf được chuyển đổi trong trường payload.
• payload. Chứa thông điệp Protobuf được chuyển đổi thực tế tương ứng với payloadType.

Một trường khác là tùy chọn.

• clientMsgId. Chứa ID thông điệp được gán bởi client.

Định nghĩa ProtoMessage thực tế trông như sau.

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

Quy ước đặt tên¶

Các thông điệp Protobuf tạo nên cTrader Open API có thể được phân loại thành các kiểu sau:

• Thông điệp yêu cầu
• Thông điệp phản hồi
• Thông điệp sự kiện
• Thông điệp mô hình

Thông điệp yêu cầu¶

Thông điệp yêu cầu được sử dụng để hỏi backend của cTrader về thông tin hoặc thực hiện các thao tác khác nhau.

Thông điệp yêu cầu được đánh dấu bằng Req ở cuối tên tương ứng của chúng. Ví dụ, thông điệp ProtoOAAssetListReq yêu cầu backend của cTrader trả về danh sách tất cả các tài sản có sẵn để giao dịch cho một tài khoản được ủy quyền hiện tại.

Thông điệp phản hồi¶

Thông điệp phản hồi đánh dấu dữ liệu được nhận từ backend của cTrader.

Thông điệp phản hồi được đánh dấu bằng Res ở cuối tên tương ứng của chúng. Như một minh họa, thông điệp ProtoOAAssetListRes có một trường lặp lại (asset) chứa tất cả các tài sản mà tài khoản được ủy quyền hiện tại có thể giao dịch.

Thông điệp sự kiện¶

Thông điệp sự kiện thông báo không đồng bộ cho tất cả các thuê bao của chúng rằng một sự kiện cụ thể đã được kích hoạt.

Thông điệp sự kiện được đánh dấu bằng Event ở cuối tên tương ứng của chúng. Ví dụ, thông điệp ProtoOAMarginChangedEvent được gửi mỗi khi số lượng margin được phân bổ cho một vị thế cụ thể thay đổi.

Thông điệp mô hình¶

Thông điệp mô hình mô tả các thực thể tạo nên mô hình miền trong backend của cTrader.

Tên của các thông điệp mô hình luôn kết thúc bằng tên của thực thể mà chúng đang định nghĩa. Ví dụ, thông điệp ProtoOAAsset định nghĩa thực thể Asset.

Kho lưu trữ thông điệp ¶

Bạn có thể tải xuống phiên bản mới nhất của các tệp thông điệp Protocol Buffers của cTrader Open API từ kho lưu trữ này.

Chúng tôi khuyên bạn nên theo dõi kho lưu trữ thông điệp nếu bạn muốn được thông báo bất cứ khi nào một phiên bản mới của các tệp thông điệp được phát hành.

Biên dịch thông điệp Protobuf ¶

Khi bạn có được các thông điệp Protobuf cần thiết, bạn có thể chạy trình biên dịch Protobuf cho ngôn ngữ bạn chọn trên các tệp .proto định nghĩa các thông điệp này. Khi thành công, trình biên dịch sẽ tạo ra các lớp truy cập dữ liệu bằng ngôn ngữ bạn ưa thích.

Các lớp này cung cấp các phương thức truy cập đơn giản cho mỗi trường (như name() và set_name()) cũng như các phương thức để xử lý việc chuyển đổi và giải mã. Tên của mỗi lớp phải khớp với tên đầy đủ của mỗi thông điệp đã được biên dịch. Tại thời điểm này, bạn có thể tự do sử dụng các lớp được tạo ra trong ứng dụng của mình để điền, chuyển đổi và giải mã các thông điệp Protobuf.

Để tìm hiểu thêm về biên dịch thông điệp protobuf bằng ngôn ngữ bạn chọn.