[原文网址](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. |
- 空白目录
- API Reference 2.0
- Getting Started
- Open Authentication
- Protocol Buffers
- Protobuf Messages Reference
- Open API Messages
- Open API Model Messages
- Open API Error Codes
- Example Projects .NET
- Spotware Proxy Cloud
- Getting Started in C#
- Test Environment
- Playground
- Frequently Asked Questions
- Lesson 1. Your First App
- Lesson 2. Get Trading Data
- Lesson 3. Get Market Data
- Lesson 4. Using Trading API