报文结构

2025-06-05 08:34

报文包括终端客户端向ZOLOZ服务器发送的请求报文，以及ZOLOZ服务器向终端客户端返回的响应报文。本文详细介绍请求报文和响应报文的结构。

请求报文的结构

ZOLOZ采用的是标准的HTTP请求格式，请求由以下几部分组成：

Request-URI：应用请求的资源。
Request Method：请求方法。
Request Header：请求头。
Request Body：请求正文。

Request-URI

Request-URI指应用请求的资源，字段值格式为/api/{version}/{restfulPath}。

version：接口版本，例如v1。
restfulPath：接口路径。

Request Method

Request Method指请求方法，请求方法仅支持POST。

Request Header

Request Header指请求头，用于携带请求和客户端的附加信息。在AK/SK接入方式下，ZOLOZ网关协议包括以下Header字段。

Header字段	是否必须	描述
Request-Time	必须	请求时间。该字段值为字符串，例如`2019-04-04T12:08:56+0530`，由以下两部分组成：日期和时间字符串，遵循RFC 3339 datetime standard。时区字符串，遵循RFC 822 timezone standard。
Client-Id	必须	分配给终端客户端的客户端标识符，该字段值为16位字符串。此ID在创建账号时由ZOLOZ服务器生成，且每个终端客户端的ID具有唯一性。
Content-Type	必须	发送给ZOLOZ服务器的请求正文格式，固定值为`application/json; charset=UTF-8`。
Auth-Type	必须	固定值为AKSK，用于标识使用的是AK/SK接入方式。
Access-Key	必须	用于身份验证和授权的凭证，客户可以在Portal上获取。
Signature	必须	签名内容，采Base64编码。

Request Body

Request Body指请求正文，用于携带请求报文内容，包含API的输入参数。报文内容为JSON格式的字符串。

完整的HTTP请求示例

copy
POST /api/v1/zoloz/authentication/test 
Content-Type: application/json;charset=UTF-8
Client-Id: 2188489224744639
Request-Time: 2025-05-12T11:37:16+0000
Auth-Type: AKSK
Access-Key:5pVg7cBioWK0cwYR
Signature:7vEjIzTDZulbMp_y6wrm5306v2wTN4ipRI9JWDuesBY
{
  "title": "hello",
  "description": "just for demonstration."
}

响应报文的结构

ZOLOZ采用的是标准的HTTP响应格式，响应由以下几部分组成：

HTTP Status：请求的处理状态。
Response Header：响应头。
Response Body：响应正文。

HTTP Status

HTTP Status指请求的处理状态，ZOLOZ网关协议使用的是标准的HTTP响应代码，详见RFC 7231。

Response Header

Response Header指响应头，包括以下Header字段。

Header字段	描述
Response-Time	响应时间。该字段值为字符串，例如`2019-04-04T12:08:56+0530`，由以下两部分组成：日期和时间字符串，遵循RFC 3339 datetime standard。时区字符串，遵循RFC 822 timezone standard。
Content-Type	返回给商户的响应正文格式，固定值为`application/json; charset=UTF-8`。有关Content-Type字段的更多信息，详见RFC 7231。
Signature	报文签名相关信息。

Response Body

Response Body指响应正文，用于携带响应报文内容，包含API的输出参数。报文内容为JSON格式的字符串。有关内容结构的更多信息，详见各API接口文档。

完整的HTTP响应示例

copy
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2019-11-19T21:56:15+0800
Signature: nXbb7SfBe90o1LtOD8NUq_nY6hf1TPW-_PnyjbENCwg
{
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "{\"title\":\"hello\",\"description\":\"just for demonstration.\"}",
        "resultStatus": "S"
    }
}