ZOLOZZOLOZDOCS

消息结构

消息包括：终端客户端发送到 ZOLOZ 服务器的请求，以及 ZOLOZ 服务器发送到终端客户端的响应。此文介绍了请求消息和响应消息的结构。

请求消息的结构

ZOLOZ 采用的是标准的 HTTP request 请求格式，由 Request-URI，method，header，和 body 组成。HTTP request 结构如下图所示：

HTTP Request Structure.png

Request-URI

应用请求的资源。 该 header 字段值格式为 /api/{version}/{restfulPath}，其中

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

Request Method

请求方法仅接受：POST。

Request Header

Request Header 包含了请求和客户端的附加信息。ZOLOZ 网关协议包括以下 header 字段：

Request-Time （必需）

请求时间。字段值为字符串，由以下两部分组成：

例如，2019-04-04T12:08:56+0530。

Content-Type （必需）

发送给 ZOLOZ 服务器的请求正文的媒体类型。ZOLOZ 网关协议仅支持以下两种内容格式：

  • application/json; charset=UTF-8：适用于未加密请求。
  • text/plain; charset=UTF-8：适用于加密请求。

有关 Content-Type 字段更多信息，请参见 RFC 7231。

Client-Id （必需）

分配给终端客户端的客户端标识符。此 ID 在创建帐号时由 ZOLOZ 服务器生成，且每个终端客户端的 ID 具有唯一性。该字段值为 16 位的字符串。

Signature （必需）

消息签名相关信息。该字段值为列表，由以下2 个键值对组成，用逗号隔开：

  • algorithm：用于请求签名的算法。仅支持 RSA256 。
  • signature：签名内容。键值必须采用 Base64 编码。

以下是一个有效的 signature header 字段示例：

copy
signature: algorithm=RSA256, signature=IpmAgtDqkjOz5sEEVlEq8OkdShXMJyXaK+6gtX/idB3+Hlhqnzdf90redIiJkawUlrY+icf1NhzSISiULGIAih72y/QRg/LlyWIWRE+GHx+k7Wl1wEYazvXRDQWF2TIia7SyyIhtjqIXj4BZ+409X72SOnx21qOU5eKxkgJQ8ZEVg5BFzXe0E//ISxJURBkVC1Q8v+7mnuT+YzgKvD1aMo16sYZih9ueTlj4xDPC8nKEoT+WJGjbdV7Ww/PXP419bGii9e7agLdxudGjD2B9d/IeUj8/w75u6V7PtdS8jCpyZQ0a28PcpvMD7yQ5f0odh7/6xGL6jECx3Y2YiuYCkw==

有关签名请求和验证签名的更多信息，请参见 消息签名和签名验证。

Encrypt （可选）

消息加密信息。该字段值为列表，由以下2 个键值对组成，用逗号隔开：

  • algorithm：用于加密请求的算法。仅支持 RSA_AES。
  • symmetricKey：以 RSA 加密的 AES 密钥。键值必须采用 Base64 编码。

以下是一个有效的 encrypt header 字段示例：

copy
encrypt: algorithm=RSA_AES, symmetricKey=FxE+siNhE2eQsnbui/6llu6TG9CaXFmT8gb2Z5bsvf2WGlAnoXoBrcB1bYodBnRs/CzSeEewFc4HOIqHejTepHehy86M9DUdefjYC783+LGBstQTPlLGsqcsYxPJTMCGYfTD6DSSXwqtKSiqD6q6C96zkp3/Q2ScmCAJprqtcA5SUj+cRmIdtG1OStSdHrQ+SstT74pwMbv1qlHbTeitZMTt5GNFXnhT1B3htS1sFb0BQ2OA+V2BtPW/izEP5ebrkfNQWmQKd6gc/i0j/DGBw4DQaxNfNvy2JHAljL5mP/ES9X0DJS6/MkimfDwXsSsTANWsjFfIoTodRn223HQC0w==

有关加密和解密请求的更多信息，请参见 消息加密和解密。

Request Body

Request Body 用于携带请求消息内容，包含 API 的输入参数。未加密请求和加密请求各有不同的内容格式。

  • 未加密请求的消息内容为 JSON 格式的字符串。Content-Type header 字段必须相应地设置为 application/json。
  • 加密请求 消息内容是用 Base64 编码加密数据的字符串。Content-Type header 字段必须相应地设置为 text/plain。

有关内容结构的更多具体信息，请参见各个 API 的 API 规范。

完整 HTTP request 示例

以下分别是未加密和加密请求示例。

未加密请求示例

copy
POST /api/v1/zoloz/authentication/test HTTP/1.1
Content-Type: application/json; charset=UTF-8
Client-Id: 2089012345678900
Request-Time: 2020-01-01T12:00:00+0800
Signature: algorithm=RSA256, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m

{
"title": "hello",
"description": "just for demonstration."
}

加密请求示例

copy
POST /api/v1/zoloz/authentication/test HTTP/1.1
Content-Type: text/plain; charset=UTF-8
Client-Id: 2089012345678900
Request-Time: 2020-01-01T12:00:00+0800
Signature: algorithm=RSA256, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m
Encrypt: algorithm=RSA_AES, symmetricKey=FxE+siNhE2eQsnbui/6llu6TG9CaXFmT8gb2Z5bsvf2WGlAnoXoBrcB1bYodBnRs/CzSeEewFc4HOIqHejTepHehy86M9DUdefjYC783+LGBstQTPlLGsqcsYxPJTMCGYfTD6DSSXwqtKSiqD6q6C96zkp3/Q2ScmCAJprqtcA5SUj+cRmIdtG1OStSdHrQ+SstT74pwMbv1qlHbTeitZMTt5GNFXnhT1B3htS1sFb0BQ2OA+V2BtPW/izEP5ebrkfNQWmQKd6gc/i0j/DGBw4DQaxNfNvy2JHAljL5mP/ES9X0DJS6/MkimfDwXsSsTANWsjFfIoTodRn223HQC0w==

r8w8wbc8Nv6sC2meJzArtGjDkbiAzg55UaDiq7TId1a7uzcv18qpOxVkXvqa3q/6TPemDDItZ79oHMzDJyvAngYqfpZZaedArWPCDeddqUl62zU5VwaB1NVhNmjHLNQ6bA1LxpsnMGnb6n8iWAEU4MtJ3TpXerMY6RToSBbI/IBA4MJFbXds0z6XLqQh9XNrLL/J0FUSV0XGFiBRxVMvUP2ytzEKh9HE6fqX/ZqTqadtp89PRTJZM87Rkb3oPdJAlaM7JUaIznGrtKe45UwjtrdYk86QhOmpWXj4L2g0Gww=

响应消息的结构

ZOLOZ 采用的是标准的 HTTP response 响应格式，由 HTTP status，header，和 body 组成。HTTP response 结构如下图所示：

Response Structure.png

HTTP status

请求的处理状态。 ZOLOZ 网关协议使用的是标准 HTTP response 代码。有关更多信息，请参见

RFC 7231。

Response Header

Trace-Id

为每个 API 调用生成的唯一 ID。

Response-Time

响应时间。字段值为字符串，由以下两部分组成：

例如，2019-04-04T12:08:56+0530。

Content-Type

返回商户的响应正文媒体类型。仅支持以下两种内容格式：

  • application/json; charset=UTF-8：适用于未加密响应。
  • text/plain; charset=UTF-8：适用于加密响应。

有关 Content-Type 字段更多信息，请参见 RFC7231。

Signature

消息签名相关信息。该字段值为列表，由以下2 个键值对组成，用逗号隔开：

  • algorithm：用于签名请求的算法。仅接受 RSA256 。
  • signature：签名内容。键值必须采用 Base64 编码。

以下是一个有效的 signature header 字段示例：

copy
signature: algorithm=RSA256, signature=QexLgtKpdjOz5sEEVlEq8OkdShXMJyXaK+6gtX/idB3+Hlhqnzdf90redIiJkawUlrY+icf1NhzSISiULGIAih72y/QRg/LlyWIWRE+GHx+k7Wl1wEYazvXRDQWF2TIia7SyyIhtjqIXj4BZ+409X72SOnx21qOU5eKxkgJQ8ZEVg5BFzXe0E//ISxJURBkVC1Q8v+7mnuT+YzgKvD1aMo16sYZih9ueTlj4xDPC8nKEoT+WJGjbdV7Ww/PXP419bGii9e7agLdxudGjD2B9d/IeUj8/w75u6V7PtdS8jCpyZQ0a28PcpvMD7yQ5f0odh7/6xGL6jECx3Y2YiuYCky++

有关签名响应和验证签名的更多信息，请参见 消息签名和签名验证。

Encrypt

消息加密信息。该字段值为列表，由以下2 个键值对组成，用逗号隔开：

  • algorithm：用于加密请求的算法。仅支持 RSA_AES。
  • symmetricKey：以 RSA 加密的 AES 密钥。键值必须采用 Base64 编码.

以下是一个有效的 encrypt header 字段示例：

copy
encrypt: algorithm=RSA_AES, symmetricKey=HnI+keXgI9eQsnbui/6llu6TG9CaXFmT8gb2Z5bsvf2WGlAnoXoBrcB1bYodBnRs/CzSeEewFc4HOIqHejTepHehy86M9DUdefjYC783+LGBstQTPlLGsqcsYxPJTMCGYfTD6DSSXwqtKSiqD6q6C96zkp3/Q2ScmCAJprqtcA5SUj+cRmIdtG1OStSdHrQ+SstT74pwMbv1qlHbTeitZMTt5GNFXnhT1B3htS1sFb0BQ2OA+V2BtPW/izEP5ebrkfNQWmQKd6gc/i0j/DGBw4DQaxNfNvy2JHAljL5mP/ES9X0DJS6/MkimfDwXsSsTANWsjFfIoTodRn223HQC00++

有关加密和解密响应的更多信息，请参见 消息加密和解密。

Response Body

Response Body 用于携带返回消息内容，包含 API 的输出参数。未加密响应和加密响应各有不同的内容格式。

  • 未加密响应的消息内容为 JSON 格式的字符串。Content-Type header 字段必须相应地设置为 application/json。
  • 加密响应的消息内容是用 Base64 编码加密数据的字符串。Content-Type header 字段必须相应地设置为 text/plain。

有关内容结构的更多具体信息，请参见各个 API 的 API 规范。

完整 HTTP response 示例

以下分别是未加密和加密响应示例。

未加密响应示例

copy
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2019-11-19T21:56:15+0800
Signature: algorithm=RSA256, signature=SGnqy/sC1sbrfK+jAl0ATJwtqUg4jUhkqpPheEYPgnM+20P69NsdrL8BB/ml5ehfFVzsst1bzwEYpDNZvqqNSBo2BPVg78pjJEk0GGNIu7NQ/pyRncYy3pIIXvr91lIvINysHcw8AgUEXRLtjMf1ktQN2OsA3+OFKB6Cf7BrKNnxjeF1lSjzbTk2ua+z1unGHUOeA9GBloSL3rL8ngC/Zqn24/eHWyKJrMFnq1jv+IhOVCqeY4knVFcPgp/bFBs4gyTdE1G1fCK5xmzk9Co8dK0wr6KcC872evBGz7SCMYZCn6Y8O5uRqS9I6F26yKKdqw8PZv2rlwJFsX21l7wRSQ==

{
  "title": "hello",
  "description": "just for demonstration."
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  }
}

加密响应示例

copy
HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Response-Time: 2019-02-23T01:45:57+0000
Signature: algorithm=RSA256, signature=imNNW52LHemfAiUFqek4QQg3ZkdHBGEUOs2SBx0OxPGBIBC0bmpu0%2BviBH%2Bh9w86VTooveJmKQSBVIf0i7hQWXqyd5Qibz49d4k9AhIhTjBKQF1VZTlJUrlphWvisSa9zn5wl3P74v9Z4CDVvHfL3wZzfwg8ujo13nSYjYdsswhSZwkGUgkSCDjq2ObtsPMHG6ZRuzrTjW6tCrqTe6EY4HyHg1mWnsAj12i1b%2FnKNayP%2FCpAe%2BT0%2Fn66NeLGjR9hjTYJ8XKKNoZ5vW%2BVYjWiDt8XWSb3KEO2Zh5Cofswe85sVPnk2S%2BvbN0nlPNU0zlJJJK6ifoSyl%2FSKI6Siu05xw%3D%3D
Encrypt: algorithm=RSA_AES, symmetricKey=eXhw3n3fdpfruNv2kh9cJQ4NzqhNhjKjCynAu6Kn92p0WPY77d8DHJV5Y4QE9fShsW%2FYZIVhCtiZSC2bBS%2F1m9HnCwhKiWzKWTwo44J692DU%2B24Yty%2FHTalqD7QWoOOd0HCskrKFHgf4INE9PMskGnZbp4B7yuLmaUEtuo8FIFNB4e%2FCIL1DhBMdsgcYL%2FiWLylNbpXztE8kMVjoEeOsz%2FbBr3Z22A4%2BQveAIDEc5sr9cjkzCB2gJsjNt4bZUWiZfP8BPLV0QEEh9mhmqzprNao2x9DsuShFcjyc3db%2BZcbMOuI8NxI0V%2FwTDi23%2BloH6Q1Mg0QgWFORlJG9da8s7Q%3D%3D

0JR682PMFgoc2ttribGxpl3f/7rNvjwpmoaAvahki1RxWUSO6mKxyQf87OUgQxQULGabLL4Q5vjFx8XvW/ugvpFexfqLojDeMgNMTyJpkT8=