Protobuf と JSON

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を使用すると、データの構造を1度だけ定義する必要があります。これは、.protoファイルでProtobufメッセージタイプを指定することによって行われます。

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

ご覧の通り、メッセージ形式はシンプルです。各メッセージタイプには1つ以上の一意に番号付けされたフィールドがあり、各フィールドには名前と値の型があります。値の型は数値（整数または浮動小数点）、ブール値、文字列、生のバイト、または（上記の例のように）他のProtocol Bufferメッセージ型である場合があります。これにより、データを階層的に構造化できます。

Protocol Bufferファイルの書き方についての詳細は、Protocol Buffer言語ガイドを参照してください。

Protocol Buffersについての詳細は、こちらをご覧ください。

Protobufの送受信のチュートリアルについては、こちらをクリックしてください。

ProtoMessages

Protobufを使用する際には、Spotwareによって設計されたProtoMessageオブジェクトの送受信を行います。

ネットワークの断片化を処理するため、メッセージの送信には次のフレーム構造が使用されます。

1
2
3
4

 +--------------------------+-----------------------------------------+  
 | メッセージの長さ（4バイト） | シリアル化されたProtoMessageオブジェクト（バイト配列） |  
 +--------------------------+-----------------------------------------+  
                            |<---------- メッセージの長さ ------------->|

各ProtoMessageには、次の構造があります。

1
2
3
4
5

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

この構造には2つの必須フィールドが含まれます。

• payloadType。 ProtoPayloadType IDを含みます。 このフィールドは、payloadフィールドにシリアル化されたProtobufオブジェクトのタイプを示します。
• payload。 payloadTypeに対応する実際のシリアル化されたProtobufメッセージを含みます。

もう1つのフィールドはオプションです。

• clientMsgId。 クライアントが割り当てたメッセージIDを含みます。

実際の`ProtoMessage“定義は

次のようになります。

1
2
3
4
5
6
7
8

message ProtoMessage {  
    required uint32 payloadType = 1; //ProtoPayloadTypeのIDまたはその他の
    カスタム PayloadTypes (例: ProtoCHPayloadType).  
    optional bytes payload = 2; // payloadTypeに対応するシリアル化されたProtobufメッセージ。  
    optional string clientMsgId = 3; //クライアントが割り当てたリクエストメッセージID。  
}

命名規則

cTrader Open APIを形成するProtobufメッセージは、次のタイプに分類できます。

• リクエストメッセージ
• レスポンスメッセージ
• イベントメッセージ
• モデルメッセージ

リクエストメッセージ

リクエストメッセージは、cTraderバックエンドに情報を要求したり、さまざまな操作を実行するために使用されます。

リクエストメッセージは、各自の名前の末尾にReqを付けてマークされます。 たとえば、ProtoOAAssetListReqメッセージは、cTraderバックエンドに現在認証されているアカウントが取引できるすべての資産のリストを返すように要求します。

レスポンスメッセージ

レスポンスメッセージは、cTraderバックエンドから受信したデータをマークします。

レスポンスメッセージは、各自の名前の末尾にResを付けてマークされます。 たとえば、ProtoOAAssetListResメッセージには、現在認証されているアカウントが取引できるすべての資産が含まれる繰り返しフィールド（asset）があります。

イベントメッセージ

イベントメッセージは、特定のイベントがトリガーされたことをすべてのサブスクライバに非同期に通知します。

イベントメッセージは、各自の名前の末尾にEventを付けてマークされます。 たとえば、ProtoOAMarginChangedEventは、特定のポジションに割り当てられた証拠金額が変更されるたびに送信されます。

モデルメッセージ

モデルメッセージは、cTraderバックエンドのドメインモデルを構成するエンティティを記述します。

モデルメッセージの名前は、常に定義されているエンティティの名前で終わります。 たとえば、ProtoOAAssetメッセージは、Assetエンティティを定義します。

メッセージリポジトリ

cTrader Open APIのProtocol Buffersメッセージファイルの最新バージョンをこのリポジトリからダウンロードできます。

メッセージファイルの新しいバージョンがリリースされるたびに通知を受け取りたい場合は、メッセージリポジトリに従うことをお勧めします。

Protocol Buffersメッセージのコンパイル

必要なProtocol Buffersメッセージを取得した

ら、Protocol Buffersコンパイラ（protoc）を使用して、メッセージ定義から目的の言語のソースコードを生成できます。

次の例は、PythonでのProtocol Buffersメッセージのコンパイル方法を示しています。

protoc -I=<proto_files_dir> --python_out=<output_dir> <proto_files_dir>/<file1>.proto <proto_files_dir>/<file2>.proto ...

ここで：

• -I=<proto_files_dir>：プロトファイルのディレクトリ（このディレクトリには、インポートされる他のプロトファイルが含まれている可能性があります）。
• --python_out=<output_dir>：生成されたPythonコードの出力ディレクトリ。
• <file1>.proto <file2>.proto ...：コンパイルするプロトファイル。

この例では、Python言語用のProtocol Buffersメッセージをコンパイルしていますが、他の言語にも同様の方法でコンパイルできます。ただし、--python_outフラグは目的の言語のコード出力ディレクトリに置き換える必要があります。