序列化和反序列化消息¶

要序列化和反序列化发送到和从 cTrader 后端接收的消息，您可以使用 Protocol Buffers (Protobufs) 或 JSON (JavaScript Object Notation)。

Protobufs 与 JSON 的对比

在以下情况下，您可能需要考虑使用 JSON：

如果您希望尽可能简化集成。 JSON 易于使用，允许您将消息序列化为人类可读的字符串。
如果您在过去与其他 API 集成时使用过 JSON。在这种情况下，您可能希望坚持使用您最熟悉的格式。

相比之下，您可能会在以下情况下选择使用 Protobufs：

如果您希望使您的集成尽可能轻量。 Protobuf 消息紧凑，因此序列化和反序列化比 JSON 更快。
如果您打算主要依赖官方 SDK，因为它们提供了有用的方法和类，您可以使用这些方法和类来抽象处理 Protobufs 的最复杂部分。

Open API 消息

您可以在集成中使用的所有消息都可以在 messages GitHub 仓库 中找到。

下面，我们详细定义了每种序列化和反序列化方法。

JSON ¶

JSON 对象可以定义为简单的键值对。请注意，键始终是字符串，而值可以是不同的数据类型，如下例所示。

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

在示例中，"clientMsgId" 键的值是字符串，而 "payloadType" 键的值是整数。 "payload" 键包含另一个 JSON 对象，该对象嵌套在父对象的主体中。 "payload.keyOne" 键的值是一个整数列表。

连接到所需的端口

您只有在连接到端口 5036 时才能使用 JSON 进行操作，当 与 cTrader 后端建立连接 时。

了解如何 发送和接收 JSON。

Protocol Buffers ¶

Protocol Buffers（或 Protobufs）提供了一种语言和平台中立的、可扩展的机制来序列化结构化数据。通过使用 Protobufs，您可以以高效且可扩展的格式对结构化数据进行编码。

使用 Protobufs，您只需要定义一次数据的结构。这是通过在 .proto 文件中指定 Protobuf 消息类型来完成的。

每条 Protobuf 消息都是一个信息记录，包含一系列名称值对。下面，您可以找到一个 .proto 文件的基本示例，该文件定义了包含有关人员信息的消息。

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 消息类型，允许您分层结构化数据。

您可以在 Protocol Buffer 语言指南 中找到有关编写 .proto 文件的更多信息。

了解更多关于 Protocol Buffers 的信息。

注意

cTrader Open API 使用 Protocol Buffers 版本 2 语法。但是，您仍然可以使用所选 Protocol Buffers 编译器/SDK 的最新版本，因为它们向后兼容，并且适用于版本 2 和版本 3 的消息文件。

查看关于 发送和接收 Protobufs 的教程。

ProtoMessages ¶

在使用 Protobufs 时，您将发送和接收由 Spotware 设计的 ProtoMessage 对象。

为了处理网络碎片化，发送消息使用以下帧结构。

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

注意

系统架构是小端序（即低位在前），这意味着在发送和接收数据时必须反转长度字节。

每个 ProtoMessage 都有以下结构。

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

该结构包含两个必填字段。

payloadType. 包含 ProtoPayloadType ID。此字段表示序列化在 payload 字段中的 Protobuf 对象的类型。
payload. 包含与 payloadType 对应的实际序列化 Protobuf 消息。

另一个字段是可选的。

clientMsgId. 包含由客户端分配的消息 ID。

实际的 ProtoMessage 定义如下所示。

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 消息，您可以在定义这些消息的 .proto 文件上运行您选择的语言的 Protobuf 编译器。成功后，编译器将生成您首选语言的数据访问类。

这些类为每个字段提供了简单的访问器（如 name() 和 set_name()）以及处理序列化和反序列化的方法。每个类的名称应与编译的每个消息的完整名称匹配。此时，您可以在应用程序中自由使用生成的类来填充、序列化和反序列化 Protobuf 消息。

了解更多关于 编译 protobuf 消息 的信息，使用您选择的语言。