Сериализация и десериализация сообщений¶

Для сериализации и десериализации сообщений, отправляемых в бэкенд 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 вам нужно определить, как вы хотите структурировать свои данные, только один раз. Это делается путем указания типов сообщений Protobuf в файлах .proto.

Каждое сообщение 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 вы будете отправлять и получать объекты ProtoMessage, разработанные Spotware.

Для обработки фрагментации сети при отправке сообщений используется следующая структура фрейма.

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. Это поле обозначает тип объекта Protobuf, сериализованного в поле payload.
• payload. Содержит фактическое сериализованное сообщение Protobuf, которое соответствует payloadType.

Еще одно поле является необязательным.

• clientMsgId. Содержит идентификатор сообщения, который назначается клиентом.

Фактическое определение 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.  
}

Соглашение об именовании¶

Сообщения Protobuf, которые формируют cTrader Open API, можно разделить на следующие типы:

• Сообщения запросов
• Сообщения ответов
• Сообщения событий
• Сообщения моделей

Сообщения запросов¶

Сообщения запросов используются для запроса информации у бэкенда cTrader или выполнения различных операций.

Сообщения запросов помечаются Req в конце соответствующих имен. Например, сообщение ProtoOAAssetListReq запрашивает у бэкенда cTrader возврат списка всех активов, доступных для торговли на текущем авторизованном счете.

Сообщения ответов¶

Сообщения ответов обозначают данные, которые получены от бэкенда cTrader.

Сообщения ответов помечаются Res в конце соответствующих имен. Например, сообщение ProtoOAAssetListRes имеет повторяющееся поле (asset), которое содержит все активы, которыми может торговать текущий авторизованный счет.

Сообщения событий¶

Сообщения событий асинхронно уведомляют всех своих подписчиков о том, что определенное событие было инициировано.

Сообщения событий помечаются Event в конце соответствующих имен. Например, ProtoOAMarginChangedEvent отправляется каждый раз, когда изменяется сумма маржи, выделенной для конкретной позиции.

Сообщения моделей¶

Сообщения моделей описывают сущности, которые формируют доменную модель в бэкенде cTrader.

Имена сообщений моделей всегда заканчиваются именем сущности, которую они определяют. Например, сообщение ProtoOAAsset определяет сущность Asset.

Репозиторий сообщений ¶

Вы можете скачать последнюю версию файлов сообщений Protocol Buffers cTrader Open API из этого репозитория.

Мы рекомендуем вам следить за репозиторием сообщений, если вы хотите получать уведомления о выпуске новой версии файлов сообщений.

Компиляция сообщений Protobuf ¶

После получения необходимых сообщений Protobuf вы можете запустить компилятор Protobuf для выбранного вами языка на файлах .proto, определяющих эти сообщения. В случае успеха компилятор сгенерирует классы доступа к данным на вашем предпочитаемом языке.

Эти классы предоставляют простые методы доступа для каждого поля (такие как name() и set_name()), а также методы для обработки сериализации и десериализации. Имя каждого класса должно соответствовать полному имени каждого скомпилированного сообщения. На этом этапе вы можете свободно использовать сгенерированные классы в своем приложении для заполнения, сериализации и десериализации сообщений Protobuf.

Чтобы узнать больше о компиляции сообщений protobuf с использованием выбранного вами языка.