تسلسل وإلغاء تسلسل الرسائل¶

لتسلسل وإلغاء تسلسل الرسائل المرسلة إلى ومن خادم 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. يحتوي على معرف ProtoPayloadType. يشير هذا الحقل إلى نوع كائن Protobuf المتسلسل في حقل payload.
• payload. يحتوي على رسالة Protobuf المتسلسلة الفعلية التي تتوافق مع payloadType.

هناك حقل آخر اختياري.

• clientMsgId. يحتوي على معرف الرسالة الذي يتم تعيينه من قبل العميل.

يبدو تعريف 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 التي تشكل Open API في cTrader إلى الأنواع التالية:

• رسائل الطلب
• رسائل الاستجابة
• رسائل الأحداث
• رسائل النموذج

رسائل الطلب¶

تُستخدم رسائل الطلب لطلب معلومات من خادم cTrader أو تنفيذ عمليات مختلفة.

يتم تمييز رسائل الطلب بـ Req في نهاية أسمائها. على سبيل المثال، تطلب رسالة ProtoOAAssetListReq من خادم cTrader إرجاع قائمة بجميع الأصول المتاحة للتداول للحساب المصرح به حالياً.

رسائل الاستجابة¶

رسائل الاستجابة تحدد البيانات المستلمة من خادم cTrader.

يتم تمييز رسائل الاستجابة بـ Res في نهاية أسمائها. كمثال توضيحي، تحتوي رسالة ProtoOAAssetListRes على حقل متكرر (asset) يحتوي على جميع الأصول التي يمكن للحساب المصرح به حالياً تداولها.

رسائل الأحداث¶

تقوم رسائل الأحداث بإخطار جميع المشتركين فيها بشكل غير متزامن عند حدوث حدث معين.

يتم تمييز رسائل الأحداث بـ Event في نهاية أسمائها. على سبيل المثال، يتم إرسال ProtoOAMarginChangedEvent في كل مرة يتم فيها تغيير مقدار الهامش المخصص لمركز معين.

رسائل النموذج¶

تصف رسائل النموذج الكيانات التي تشكل نموذج المجال في خادم cTrader.

تنتهي أسماء رسائل النموذج دائماً باسم الكيان الذي تحدده. على سبيل المثال، تحدد رسالة ProtoOAAsset كيان Asset.

مستودع الرسائل ¶

يمكنك تنزيل أحدث إصدار من ملفات رسائل Protocol Buffers الخاصة بـ Open API من cTrader من هذا المستودع.

نوصي بمتابعة مستودع الرسائل إذا كنت ترغب في تلقي إشعار عند إصدار نسخة جديدة من ملفات الرسائل.

تجميع رسائل Protobuf ¶

بمجرد الحصول على رسائل Protobuf المطلوبة، يمكنك تشغيل مترجم Protobuf للغة التي اخترتها على ملفات .proto التي تحدد هذه الرسائل. عند النجاح، سيقوم المترجم بإنشاء فئات الوصول إلى البيانات بلغتك المفضلة.

توفر هذه الفئات وسائل وصول بسيطة لكل حقل (مثل name() و set_name()) بالإضافة إلى طرق للتعامل مع التسلسل وإلغاء التسلسل. يجب أن يتطابق اسم كل فئة مع الاسم الكامل لكل رسالة تم تجميعها. في هذه المرحلة، يمكنك استخدام الفئات المُنشأة بحرية في تطبيقك لتعبئة رسائل Protobuf وتسلسلها وإلغاء تسلسلها.

لمعرفة المزيد حول تجميع رسائل protobuf باستخدام اللغة التي تختارها.