메시지 직렬화 및 역직렬화¶

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를 사용하면 데이터를 어떻게 구조화할지 한 번만 정의하면 됩니다. 이는 .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;  
}

보시다시피 메시지 형식은 간단합니다. 각 메시지 유형에는 하나 이상의 고유 번호가 지정된 필드가 있으며, 각 필드에는 이름과 값 유형이 있습니다. 값 유형은 숫자(정수 또는 부동 소수점), 부울, 문자열, 원시 바이트 또는 (위 예제와 같이) 다른 Protocol Buffer 메시지 유형일 수 있어 데이터를 계층적으로 구조화할 수 있습니다.

.proto 파일 작성에 대한 자세한 내용은 Protocol Buffer 언어 가이드에서 확인할 수 있습니다.

Protocol Buffers에 대해 자세히 알아보세요.

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

구조에는 두 개의 필수 필드가 있습니다.

• payloadType. ProtoPayloadType ID를 포함합니다. 이 필드는 payload 필드에 직렬화된 Protobuf 객체의 유형을 나타냅니다.
• payload. payloadType에 해당하는 실제 직렬화된 Protobuf 메시지를 포함합니다.

다른 하나의 필드는 선택 사항입니다.

• 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 메시지 컴파일에 대해 더 알아보세요.