Mesajları serileştirme ve seri durumdan çıkarma¶

cTrader arka ucuna gönderilen ve oradan alınan mesajları serileştirmek ve seri durumdan çıkarmak için Protocol Buffers (Protobuf'lar) veya JSON (JavaScript Nesne Gösterimi) kullanabilirsiniz.

Aşağıda, her serileştirme ve seri durumdan çıkarma yöntemini ayrıntılı olarak tanımlıyoruz.

JSON ¶

JSON nesneleri basit anahtar-değer çiftleri olarak tanımlanabilir. Anahtarların her zaman dizeler olduğunu, değerlerin ise aşağıdaki örnekte gösterildiği gibi farklı veri türlerinde olabileceğini unutmayın.

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

Örnekte, "clientMsgId" anahtarının değeri bir dize iken, "payloadType" anahtarının değeri bir tam sayıdır. payload anahtarı, üst nesnenin gövdesine yerleştirilmiş başka bir JSON nesnesi içerir. payload.keyOne anahtarının değeri bir tam sayı listesidir.

JSON gönderme ve alma yöntemini öğrenin.

Protocol Buffers ¶

Protocol Buffers (veya Protobuf'lar), yapılandırılmış verileri serileştirmek için dil ve platformdan bağımsız, genişletilebilir bir mekanizma sunar. Protobuf'ları kullanarak, yapılandırılmış verileri verimli ancak genişletilebilir bir formatta kodlayabilirsiniz.

Protobuf'larla, verilerinizin nasıl yapılandırılmasını istediğinizi yalnızca bir kez tanımlamanız gerekir. Bu, .proto dosyalarında Protobuf mesaj türleri belirtilerek yapılır.

Her Protobuf mesajı, bir dizi ad-değer çifti içeren bir bilgi kaydıdır. Aşağıda, bir kişi hakkında bilgi içeren bir mesajı tanımlayan temel bir .proto dosyası örneği bulabilirsiniz.

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

Gördüğünüz gibi, mesaj formatı basittir. Her mesaj türünün bir veya daha fazla benzersiz numaralı alanı vardır ve her alanın bir adı ve bir değer türü vardır; değer türleri sayılar (tam sayı veya kayan nokta), boole'lar, dizeler, ham baytlar veya hatta (yukarıdaki örnekte olduğu gibi) diğer Protocol Buffer mesaj türleri olabilir, bu da verilerinizi hiyerarşik olarak yapılandırmanıza olanak tanır.

.proto dosyaları yazma hakkında daha fazla bilgiyi Protocol Buffer dil kılavuzunda bulabilirsiniz.

Protocol Buffers hakkında daha fazla bilgi edinin.

Protobuf'ları gönderme ve alma hakkında bir eğitim görüntüleyin.

ProtoMesajlar ¶

Protobuf'larla çalışırken, Spotware tarafından tasarlanmış ProtoMessage nesneleri gönderip alacaksınız.

Ağ parçalanmasını yönetmek için, mesaj gönderme aşağıdaki çerçeve yapısını kullanır.

1
2
3
4

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

Her ProtoMessage aşağıdaki yapıya sahiptir.

1
2
3
4
5

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

Yapı iki zorunlu alan içerir.

• payloadType. ProtoPayloadType kimliğini içerir. Bu alan, payload alanında serileştirilmiş Protobuf nesnesinin türünü belirtir.
• payload. payloadType ile eşleşen gerçek serileştirilmiş Protobuf mesajını içerir.

Bir diğer alan isteğe bağlıdır.

• clientMsgId. İstemci tarafından atanan mesaj kimliğini içerir.

Gerçek ProtoMessage tanımı aşağıdaki gibidir.

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

Adlandırma kuralı¶

cTrader Open API'yi oluşturan Protobuf mesajları aşağıdaki türlere ayrılabilir:

• İstek mesajları
• Yanıt mesajları
• Olay mesajları
• Model mesajları

İstek mesajları¶

İstek mesajları, cTrader arka ucundan bilgi istemek veya çeşitli işlemler gerçekleştirmek için kullanılır.

İstek mesajları, ilgili adlarının sonunda Req ile işaretlenir. Örneğin, ProtoOAAssetListReq mesajı, cTrader arka ucundan şu anda yetkilendirilmiş bir hesaba işlem için mevcut tüm varlıkların bir listesini döndürmesini ister.

Yanıt mesajları¶

Yanıt mesajları, cTrader arka ucundan alınan verileri işaretler.

Yanıt mesajları, ilgili adlarının sonunda Res ile işaretlenir. Bir örnek olarak, ProtoOAAssetListRes mesajı, şu anda yetkilendirilmiş hesabın işlem yapabileceği tüm varlıkları içeren tekrarlanan bir alana (asset) sahiptir.

Olay mesajları¶

Olay mesajları, belirli bir olayın tetiklendiğini tüm abonelerine eşzamansız olarak bildirir.

Olay mesajları, ilgili adlarının sonunda Event ile işaretlenir. Örneğin, ProtoOAMarginChangedEvent, belirli bir pozisyona ayrılan marjin miktarı her değiştiğinde gönderilir.

Model mesajları¶

Model mesajları, cTrader arka ucundaki alan modelini oluşturan varlıkları tanımlar.

Model mesajlarının adları her zaman tanımladıkları varlığın adıyla biter. Bir örnek olarak, ProtoOAAsset mesajı Asset varlığını tanımlar.

Mesaj deposu ¶

cTrader Open API Protokol Tamponları mesaj dosyalarının en son sürümünü bu depodan indirebilirsiniz.

Mesaj dosyalarının yeni bir sürümü yayınlandığında bildirim almak isterseniz mesaj deposunu takip etmenizi öneririz.

Protobuf mesajlarını derleyin ¶

Gerekli Protobuf mesajlarını edindikten sonra, seçtiğiniz dil için Protobuf derleyicisini bu mesajları tanımlayan .proto dosyaları üzerinde çalıştırabilirsiniz. Başarılı olursa, derleyici tercih ettiğiniz dilde veri erişim sınıfları oluşturacaktır.

Bu sınıflar, her alan için basit erişimciler (name() ve set_name() gibi) ve ayrıca serileştirme ve seri durumdan çıkarma işlemlerini yönetmek için yöntemler sağlar. Her sınıfın adı, derlenen her mesajın tam adıyla eşleşmelidir. Bu noktada, oluşturulan sınıfları uygulamanızda Protobuf mesajlarını doldurmak, serileştirmek ve seri durumdan çıkarmak için serbestçe kullanabilirsiniz.

Seçtiğiniz dili kullanarak Protobuf mesajlarını derleme hakkında daha fazla bilgi edinmek için.