コンテンツにスキップ

メッセージのシリアライゼーションとデシリアライゼーション

cTraderバックエンドとの間で送受信されるメッセージをシリアライズおよびデシリアライズするには、Protocol Buffers（Protobufs）またはJSON（JavaScript Object Notation）を使用できます。

Protobufs vs JSON

以下の場合、JSONの使用を検討することをお勧めします:

  • 統合を可能な限り簡素化したい場合。 JSONは使いやすく、メッセージを人間が読める文字列にシリアライズできます。
  • 過去に他のAPIとの統合でJSONを使用したことがある場合。 その場合、最も慣れている形式に固執することをお勧めします。

一方、以下の場合、Protobufsの使用を選択することをお勧めします:

  • 統合を可能な限り軽量にしたい場合。 Protobufメッセージはコンパクトであるため、JSONと比較してシリアライゼーションとデシリアライゼーションが高速です。
  • 公式SDKを主に使用する予定がある場合。公式SDKは、Protobufsを扱う際の最も複雑な部分を抽象化するために使用できる便利なメソッドとクラスを提供します。

Open APIメッセージ

統合で使用できるすべてのメッセージは、メッセージGitHubリポジトリにあります。

以下では、シリアライゼーションとデシリアライゼーションの各方法を詳細に定義します。

JSON

JSONオブジェクトは、単純なキーと値のペアとして定義できます。 キーは常に文字列であり、値は以下の例に示すように異なるデータ型であることに注意してください。

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

この例では、"clientMsgId"キーの値は文字列であり、"payloadType"キーの値は整数です。 "payload"キーには、親オブジェクトの本体にネストされた別のJSONオブジェクトが含まれています。 "payload.keyOne"キーの値は整数のリストです。

必要なポートに接続

JSONを使用するには、cTraderバックエンドとの接続を確立する際にポート5036に接続する必要があります。

JSONの送受信方法を学びましょう。

Protocol Buffers

Protocol Buffers（またはProtobufs）は、構造化データをシリアライズするための言語およびプラットフォームに依存しない拡張可能なメカニズムを提供します。 Protobufsを使用すると、構造化データを効率的かつ拡張可能な形式でエンコードできます。

Protobufsでは、データの構造を一度だけ定義する必要があります。 これは、.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メッセージタイプでもかまいません。これにより、データを階層的に構造化できます。

.protoファイルの作成についての詳細は、Protocol Buffer言語ガイドをご覧ください。

Protocol Buffersについて詳しく学びましょう。

注意

cTrader Open APIは、Protocol Buffersバージョン2の構文を使用します。 ただし、選択したProtocol Buffersコンパイラ/SDKの最新バージョンを使用することもできます。これらは後方互換性があり、バージョン2とバージョン3のメッセージファイルの両方で動作します。

Protobufsの送受信のチュートリアルをご覧ください。

ProtoMessages

Protobufsを使用する場合、Spotwareが設計したProtoMessageオブジェクトを送受信します。

ネットワークフラグメンテーションを処理するために、メッセージの送信には以下のフレーム構造を使用します。

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   |  
 +----------------------+

この構造には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; //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.  
}

命名規則

cTrader Open APIを構成するProtobufメッセージは、以下のタイプに分類できます:

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

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

リクエストメッセージは、それぞれの名前の末尾に Req とマークされます。 例えば、ProtoOAAssetListReq メッセージは、現在認証されているアカウントが取引可能なすべての資産のリストをcTraderバックエンドに要求します。

レスポンスメッセージ

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

レスポンスメッセージは、それぞれの名前の末尾に Res とマークされます。 例として、ProtoOAAssetListRes メッセージには、現在認証されているアカウントが取引可能なすべての資産を含む繰り返しフィールド（asset）があります。

イベントメッセージ

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

イベントメッセージは、それぞれの名前の末尾に Event とマークされます。 例えば、ProtoOAMarginChangedEvent は、特定のポジションに割り当てられたマージンの量が変更されるたびに送信されます。

モデルメッセージ

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

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

メッセージリポジトリ

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

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

Protobufメッセージのコンパイル

必要なProtobufメッセージを取得したら、選択した言語のProtobufコンパイラをこれらのメッセージを定義する .proto ファイルに対して実行できます。 成功すると、コンパイラは選択した言語でデータアクセスクラスを生成します。

これらのクラスは、各フィールド（name() や set_name() など）のシンプルなアクセサと、シリアライゼーションおよびデシリアライゼーションを処理するメソッドを提供します。 各クラスの名前は、コンパイルされた各メッセージの完全な名前と一致する必要があります。 この時点で、生成されたクラスを自由にアプリケーションで使用して、Protobufメッセージを生成、シリアライズ、デシリアライズできます。

選択した言語を使用してProtobufメッセージをコンパイルする方法について詳しく学ぶことができます。