Serialisieren und Deserialisieren von Nachrichten¶

Um Nachrichten zu serialisieren und zu deserialisieren, die an das und vom cTrader-Backend gesendet werden, können Sie entweder Protocol Buffers (Protobufs) oder JSON (JavaScript Object Notation) verwenden.

Im Folgenden definieren wir jede Methode der Serialisierung und Deserialisierung im Detail.

JSON ¶

JSON-Objekte können als einfache Schlüssel-Wert-Paare definiert werden. Beachten Sie, dass Schlüssel immer Zeichenfolgen sind, während Werte unterschiedliche Datentypen haben können, wie im folgenden Beispiel gezeigt.

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

Im Beispiel ist der Wert des Schlüssels „clientMsgId" eine Zeichenfolge, während der Wert des Schlüssels „payloadType" eine Ganzzahl ist. Der Schlüssel „payload" enthält ein weiteres JSON-Objekt, das im Hauptteil des übergeordneten Objekts verschachtelt ist. Der Wert des Schlüssels „payload.keyOne" ist eine Liste von Ganzzahlen.

Erfahren Sie, wie Sie JSON senden und empfangen können.

Protocol Buffers ¶

Protocol Buffers (oder Protobufs) bieten einen sprach- und plattformneutralen, erweiterbaren Mechanismus zur Serialisierung strukturierter Daten. Durch die Verwendung von Protobufs können Sie strukturierte Daten in einem effizienten und dennoch erweiterbaren Format kodieren.

Mit Protobufs müssen Sie nur einmal definieren, wie Ihre Daten strukturiert werden sollen. Dies geschieht durch die Angabe von Protobuf-Nachrichtentypen in .proto-Dateien.

Jede Protobuf-Nachricht ist ein Informationsdatensatz, der eine Reihe von Name-Wert-Paaren enthält. Nachfolgend finden Sie ein einfaches Beispiel einer .proto-Datei, die eine Nachricht mit Informationen über eine Person definiert.

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

Wie Sie sehen können, ist das Nachrichtenformat einfach. Jeder Nachrichtentyp verfügt über ein oder mehrere eindeutig nummerierte Felder, und jedes Feld hat einen Namen und einen Werttyp, wobei Werttypen Zahlen (Ganzzahl oder Gleitkommazahl), boolesche Werte, Zeichenfolgen, Roh-Bytes oder sogar (wie im obigen Beispiel) andere Protocol Buffer-Nachrichtentypen sein können, sodass Sie Ihre Daten hierarchisch strukturieren können.

Weitere Informationen zum Schreiben von .proto-Dateien finden Sie im Protocol Buffer-Sprachleitfaden.

Erfahren Sie mehr über Protocol Buffers.

Sehen Sie sich ein Tutorial zum Senden und Empfangen von Protobufs an.

ProtoMessages ¶

Bei der Arbeit mit Protobufs senden und empfangen Sie ProtoMessage-Objekte, die von Spotware entwickelt wurden.

Um Netzwerkfragmentierung zu handhaben, verwendet das Senden von Nachrichten die folgende Frame-Struktur.

1
2
3
4

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

Jede ProtoMessage hat die folgende Struktur.

1
2
3
4
5

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

Die Struktur enthält zwei Pflichtfelder.

• payloadType. Enthält die ProtoPayloadType-ID. Dieses Feld gibt den Typ des Protobuf-Objekts an, das im Feld payload serialisiert ist.
• payload. Enthält die tatsächliche serialisierte Protobuf-Nachricht, die payloadType entspricht.

Ein weiteres Feld ist optional.

• clientMsgId. Enthält die Nachrichten-ID, die vom Client zugewiesen wird.

Die tatsächliche ProtoMessage-Definition sieht wie folgt aus.

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

Namenskonvention¶

Die Protobuf-Nachrichten, die cTrader Open API bilden, können in die folgenden Typen kategorisiert werden:

• Anforderungsnachrichten
• Antwortnachrichten
• Ereignisnachrichten
• Modellnachrichten

Anforderungsnachrichten¶

Anforderungsnachrichten werden verwendet, um das cTrader-Backend um Informationen zu bitten oder verschiedene Vorgänge auszuführen.

Anforderungsnachrichten sind am Ende ihrer jeweiligen Namen mit Req gekennzeichnet. Beispielsweise fordert die Nachricht ProtoOAAssetListReq das cTrader-Backend auf, eine Liste aller Assets zurückzugeben, die für ein aktuell autorisiertes Konto zum Handel verfügbar sind.

Antwortnachrichten¶

Antwortnachrichten kennzeichnen Daten, die vom cTrader-Backend empfangen werden.

Antwortnachrichten sind am Ende ihrer jeweiligen Namen mit Res gekennzeichnet. Zur Veranschaulichung: Die Nachricht ProtoOAAssetListRes verfügt über ein wiederholtes Feld (asset), das alle Assets enthält, mit denen das aktuell autorisierte Konto handeln kann.

Ereignisnachrichten¶

Ereignisnachrichten benachrichtigen alle ihre Abonnenten asynchron darüber, dass ein bestimmtes Ereignis ausgelöst wurde.

Ereignisnachrichten sind am Ende ihrer jeweiligen Namen mit Event gekennzeichnet. Beispielsweise wird ProtoOAMarginChangedEvent jedes Mal gesendet, wenn sich der Betrag der Marge ändert, die einer bestimmten Position zugewiesen ist.

Modellnachrichten¶

Modellnachrichten beschreiben die Entitäten, die das Domänenmodell im cTrader-Backend bilden.

Die Namen von Modellnachrichten enden immer mit dem Namen der Entität, die sie definieren. Beispielsweise definiert die Nachricht ProtoOAAsset die Entität Asset.

Nachrichten-Repository ¶

Sie können die neueste Version der cTrader Open API Protocol Buffers-Nachrichtendateien aus diesem Repository herunterladen.

Wir empfehlen Ihnen, dem Nachrichten-Repository zu folgen, wenn Sie benachrichtigt werden möchten, sobald eine neue Version der Nachrichtendateien veröffentlicht wird.

Protobuf-Nachrichten kompilieren ¶

Sobald Sie die erforderlichen Protobuf-Nachrichten erhalten haben, können Sie den Protobuf-Compiler für Ihre gewählte Sprache auf den .proto-Dateien ausführen, die diese Nachrichten definieren. Bei Erfolg generiert der Compiler Datenzugriffsklassen in Ihrer bevorzugten Sprache.

Diese Klassen bieten einfache Zugriffsmethoden für jedes Feld (wie name() und set_name()) sowie Methoden zur Handhabung von Serialisierung und Deserialisierung. Der Name jeder Klasse sollte mit dem vollständigen Namen jeder kompilierten Nachricht übereinstimmen. An diesem Punkt können Sie die generierten Klassen in Ihrer Anwendung frei verwenden, um Protobuf-Nachrichten zu füllen, zu serialisieren und zu deserialisieren.

Um mehr über das Kompilieren von Protobuf-Nachrichten in Ihrer bevorzugten Sprache zu erfahren.