请求与响应

提示

Shamrock 为您提供了一个支持 OneBot 标准的 HTTP API。
您可以通过发送 HTTP 请求来与 Shamrock 进行交互。

请求

提示

Shamrock 目前支持 GET 和 POST 两种请求方式。
在大部分情况下，您可以使用 GET 请求来与 Shamrock 进行交互。
但是，如果您需要向 Shamrock 发送大量数据，或者需要向 Shamrock 发送二进制数据，您需要使用 POST 请求。

GET 请求

GET 请求的 URL 由以下部分组成：

http://<host>:<port>/<endpoint>?<params>

链接中的含义如下：

• <host>：Shamrock 的 IP 地址或域名
• <port>：Shamrock 的 HTTP API 端口
• <endpoint>：Shamrock 的 HTTP API 端点
• <params>：HTTP GET 请求的参数

POST 请求

POST 请求的 URL 由以下部分组成：

http://<host>:<port>/<endpoint>

链接中的含义如下：

• <host>：Shamrock 的 IP 地址或域名
• <port>：Shamrock 的 HTTP API 端口
• <endpoint>：Shamrock 的 HTTP API 端点

请求格式

POST 请求的数据格式为 JSON

{
  "param1": "value1",
  "param2": "value2",
  ...
}

POST 请求的数据格式为表单

param1=value1&param2=value2&...

大多数情况下，推荐使用 JSON 格式的 POST 请求。

WebSocket 请求

Shamrock 支持使用 WebSocket 进行通信。

可选的 WebSocket 地址有两种：

• ws://<host>:<port>
• ws://<host>:<port>/api

区别在于，/ 除了发送和响应 API 请求外，还支持事件上报功能。

请求格式

Shamrock 使用 WebSocket 时，请求的数据格式为 JSON

{
  "action": "send_private_msg", // 请求 API 端点
  "params": {
    // 请求参数
    "user_id": 10000,
    "message": "hello"
  },
  "echo": "123456" // 自定义的回显字段
}

对于 echo 字段，Shamrock 会在响应中原样返回。

响应

Shamrock 的响应格式为 JSON

{
  "status": "ok", // 状态，ok 为成功，其他将在下文中详细说明
  "retcode": 0, // 返回码，0 为成功，非 0 为失败
  "msg": "", // 错误信息，仅在 API 调用失败时出现
  "wording": "", // 对错误信息的描述，仅在 API 调用失败时出现
  "data": {
    // 响应数据
    "message_id": 123456
  },
  "echo": "123456" // 请求中的回显字段
}

状态

Shamrock 的响应状态有以下几种：

• ok：成功
• failed：失败