Protocol Buffers · Ctrader API 2.0

[原文網址](https://connect.spotware.com/docs/open_api_2/introduction_to_protocol_buffers_v2) **Protocol buffers**或Protobuf是用于序列化結構化數據的語言和平臺中立的可擴展機制，這是一種以高效且可擴展的格式編碼結構化數據的方法。您可以定義數據的結構化方式，然后使用特殊生成的源代碼輕松地在各種數據流中使用各種語言編寫和讀取結構化數據。您可以通過在* .proto *文件中定義協議緩沖區消息類型來指定您希望如何構建序列化信息。每個協議緩沖區消息都是信息的小型邏輯記錄，包含一系列名稱 - 值對。這是* .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; } ~~~ 如您所見，消息格式很簡單 - 每種消息類型都有一個或多個唯一編號的字段，每個字段都有一個名稱和一個值類型，其中值類型可以是數字（整數或浮點數），布爾值，字符串，原始字節，甚至（如上例所示）其他協議緩沖區消息類型，允許您分層次地構建數據。您可以在中找到有關編寫.proto文件的更多信息[Protocol Buffer Language Guide](https://developers.google.com/protocol-buffers/docs/proto). 一旦定義了消息，就可以在* .proto *文件上運行應用程序語言的協議緩沖區編譯器，以生成數據訪問類。這些為每個字段提供了簡單的訪問器（如name（）和set \ _name（）），以及將整個結構序列化/解析為原始字節的方法 - 例如，如果您選擇的語言是C ++，則運行上面的例子中的編譯器將生成一個名為Person的類。然后，您可以在應用程序中使用此類來填充，序列化和檢索Person協議緩沖區消息。了解有關Protocol Buffers的更多信息[here](https://developers.google.com/protocol-buffers/docs/overview). ### Generating Protobuf Classes Protobuf是靈活的自動化解決方案，旨在簡化序列化和檢索結構化數據。使用協議緩沖區，您可以編寫要存儲的數據結構的.proto描述。由此，協議緩沖區編譯器創建一個類，該類使用有效的二進制格式實現協議緩沖區數據的自動編碼和解析。生成的類為構成協議緩沖區的字段提供getter和setter，并負責將協議緩沖區作為一個單元讀取和寫入的細節。重要的是，協議緩沖區格式支持隨著時間的推移擴展格式的想法，使得代碼仍然可以讀取用舊格式編碼的數據。下面我們將重點介紹如何使用針對C＃和Java語言的protobuf工具生成類。 **Protobuf Basics for C#** 1. 要從.proto文件生成C＃類，請使用可從此處下載的C＃類生成器:[Protocol Buffers Gen](https://connect.spotware.com/uploads/misc/Protocol%20Buffers%20Gen.rar). 解壓縮本地驅動器上的下載文件。 2. Download the latest version of Open API 2.0 .proto files from our[GitHub repository](https://github.com/spotware/Open-API-2.0-protobuf-messages)and extract them on your local drive to the same location with your Protocol Buffers Generator from the step 1. 3. Run the following command for all the protofiles: > ProtoGen.exe protofile.proto -output\_directory=*C:\\output\_folder*\--include\_imports where protofile.proto - is your .proto file name and output\_folder is the output folder name. 1.將新生成的.cs文件復制到項目中。或者，您可以在解決方案中創建類庫項目并在那里復制.cs文件。 ???? 2.將.cs文件鏈接到項目，將它們添加到項目中和/或設置項目與proto庫項目之間的依賴關系（如果您已創建庫）。將類庫項目的引用（如果有的話）添加到主項目中。 ???? 3.將Google.ProtocolBuffers.dll上的引用添加到類庫項目（如果您沒有類庫項目，則添加您的主項目）。或者，如果您使用Visual Studio，則可以使用ProtobufGenerator for Visual Studio 2015/2017 from[here](https://marketplace.visualstudio.com/items?itemName=jonasjakobsson.ProtobufGeneratorvisualstudio). 在對proto文件進行任何更改后，此擴展為您運行* protoc.exe *。要使用擴展，請安裝它，然后在visual studio屬性面板中的proto文件屬性中的Custom工具中鍵入ProtobufGenerator。 .cs文件將作為項目中proto文件的子文件放置。如果沒有生成.cs文件，可能是因為它找不到* protoc.exe *文件。您可以自己編譯它，但它也可以在塊中使用Google.Protobuf.Tools。但是，在項目中使用該塊并不是強制性的。此外，您還可以找到有關如何使用Protobuf的詳細信息 C#[here](https://developers.google.com/protocol-buffers/docs/csharptutorial). **Protobuf Basics for Java** Please find detailed information on how to use Protobuf for Java[here](https://developers.google.com/protocol-buffers/docs/javatutorial). ### ProtoMessages Open API 2.0中的網絡通信是通過ProtoMessage對象執行的 - 由Spotware設計的protobuf消息。為了處理網絡碎片，我們將使用以下幀結構將消息發送到網絡: ~~~ +--------------------------+-----------------------------------------+ | Message Length (4 bytes) | Serialized ProtoMessage object (byte[]) | +--------------------------+-----------------------------------------+ |<---------- Message Length ------------->| ~~~ ProtoMessage has the following structure: ~~~ +----------------------+ | int32 payloadType | | byte[] payload | | string clientMsgId | +----------------------+ ~~~ It contains 2 mandatory fields: * payloadType - contains the ProtoPayloadType ID. This field tells us what is the type of the protobuf object serialized in the second field. * payload - serialized protobuf message that corresponds to payloadType. And an optional field: * clientMsgId - request message ID, assigned by the client that will be returned in the response. The actual ProtoMessage definition looks as follows: ~~~ message ProtoMessage { required uint32 payloadType = 1; //Contains ID of the ProtoPayloadType or other custom PayloadTypes (e.g. ProtoCHPayloadType). optional bytes payload = 2; //Serialized protobuf message that corresponds to the payloadType optional string clientMsgId = 3; //The request message ID, assigned by the client that will be returned in the response. } ~~~ **Naming convention** Message Naming Convention All messages could be divided into the Request messages, Response messages, Event messages, and Model messages: ***Request***messages are used for sending requests to the server *Example:* ~~~ ProtoAuthReq ~~~ where Req means request command message ***Response***messages are used to receive data back from the server. *Example:* ~~~ ProtoAuthRes. ~~~ where Res means response command message. ***Event***messages are used for notifying subscribers with asynchronous messages. The classic example is ping command, its proto class name is ProtoPingEvent. The naming convention of events is ProtoEventNameEvent. ***Model***messages describe entities that participate in the Server domain model. Naming conventions of the Model messages is ProtoEntityName. *Examples:* ~~~ ProtoOrder ProtoUser ProtoPosition ~~~ ### Account Information Use the following protobuf messages for retrieving or sending the account information: | ProtoOAApplicationAuthReq | Request for authorizing an Application to work with cTrader platform Proxies. | | --- | --- | | ProtoOAApplicationAuthRes | Response to ProtoOAApplicationAuthReq | | ProtoOAAccountAuthReq | Request for authorizing a Trading Account within authorized application connection. Required for starting work with the account. | | ProtoOAAccountAuthRes | Response on ProtoOAApplicationAuthRes. | ### Trading Use the following protobuf messages for retrieving or sending the trading data: | ProtoOANewOrderReq | Request for sending new trading order. Allowed only if the accessToken field has "trade" permissions for the Trading Account. | | --- | --- | | ProtoOAExecutionEvent | Event that is returned following the successful order processing or order execution. Replaces responses for Trading requets ProtoOANewOrderReq, ProtoOACancelOrderReq, ProtoOAAmendOrderReq, ProtoOAAmendPositionSLTPReq, ProtoOAClosePositionReq. Also, event is sent when a Deposit/Withdrawal took place. | | ProtoOACancelOrderReq | Request for canceling an existing pending order. Allowed only if the access token has "trade" permissions for the Trading Account. | | ProtoOAAmendOrderReq | Request for amending existing pending order. | | ProtoOAAmendPositionSLTPReq | Request for amending StopLoss and TakeProfit for existing position. | | ProtoOAClosePositionReq | Request for closing the existing positions. | | ProtoOATrailingSLChangedEvent | Event that is returned when the level of a Trailing Stop Loss is changed. | ### Market data Use the following protobuf messages for retrieving or sending the market data: | ProtoOASymbolsForConversionReq | Request for getting a conversion chain between two assets that consists of several symbols. | | --- | --- | | ProtoOASymbolsForConversionRes | Response to ProtoOASymbolsForConversionReq. | | ProtoOADealListReq | Request for getting the deals list. | | ProtoOADealListRes | Response to getting deals list. | | ProtoOAAssetListReq | Request for the list of assets available on the Server of the Trader's Account. | | ProtoOAAssetListRes | Response to the ProtoOAAssetListReq request. | | ProtoOASymbolsListReq | Request for a list of symbols available on the Server of the Trader's Account. | | ProtoOASymbolByIdReq | Request for getting a full Symbol entity. | | ProtoOASymbolByIdRes | Response to the ProtoOASymbolByIdReq request. | | ProtoOASymbolsForConversionReq | Request for getting a conversion chain between two assets that consists of several symbols. | | ProtoOASymbolsForConversionRes | Response to the ProtoOASymbolsForConversionReq request. | | ProtoOAAssetClassListReq | Request for a list of Asset Classes available on the Server of the Trader's Account. | | ProtoOAAssetClassListRes | Responce to the ProtoOAAssetListReq request. |