mirror of
https://github.com/whitechi73/OpenShamrock.git
synced 2024-08-14 13:12:17 +08:00
121 lines
2.5 KiB
Markdown
121 lines
2.5 KiB
Markdown
---
|
||
title: 请求与响应
|
||
icon: server
|
||
---
|
||
|
||
::: tip 提示
|
||
Shamrock 为您提供了一个支持 OneBot 标准的 HTTP API。
|
||
您可以通过发送 HTTP 请求来与 Shamrock 进行交互。
|
||
:::
|
||
|
||
## 请求
|
||
|
||
::: tip 提示
|
||
Shamrock 目前支持 GET 和 POST 两种请求方式。
|
||
在大部分情况下，您可以使用 GET 请求来与 Shamrock 进行交互。
|
||
但是，如果您需要向 Shamrock 发送大量数据，或者需要向 Shamrock 发送二进制数据，您需要使用 POST 请求。
|
||
:::
|
||
|
||
### GET 请求
|
||
|
||
GET 请求的 URL 由以下部分组成：
|
||
|
||
```text
|
||
http://<host>:<port>/<endpoint>?<params>
|
||
```
|
||
|
||
链接中的含义如下：
|
||
|
||
- `<host>`：Shamrock 的 IP 地址或域名
|
||
- `<port>`：Shamrock 的 HTTP API 端口
|
||
- `<endpoint>`：Shamrock 的 HTTP API 端点
|
||
- `<params>`：HTTP GET 请求的参数
|
||
|
||
### POST 请求
|
||
|
||
POST 请求的 URL 由以下部分组成：
|
||
|
||
```text
|
||
http://<host>:<port>/<endpoint>
|
||
```
|
||
|
||
链接中的含义如下：
|
||
|
||
- `<host>`：Shamrock 的 IP 地址或域名
|
||
- `<port>`：Shamrock 的 HTTP API 端口
|
||
- `<endpoint>`：Shamrock 的 HTTP API 端点
|
||
|
||
#### 请求格式
|
||
|
||
POST 请求的数据格式为 JSON
|
||
|
||
```json
|
||
{
|
||
"param1": "value1",
|
||
"param2": "value2",
|
||
...
|
||
}
|
||
```
|
||
|
||
POST 请求的数据格式为表单
|
||
|
||
```text
|
||
param1=value1¶m2=value2&...
|
||
```
|
||
|
||
大多数情况下，推荐使用 JSON 格式的 POST 请求。
|
||
|
||
### WebSocket 请求
|
||
|
||
Shamrock 支持使用 WebSocket 进行通信。
|
||
|
||
可选的 WebSocket 地址有两种：
|
||
|
||
- `ws://<host>:<port>`
|
||
- `ws://<host>:<port>/api`
|
||
|
||
区别在于，`/` 除了发送和响应 API 请求外，还支持事件上报功能。
|
||
|
||
### 请求格式
|
||
|
||
Shamrock 使用 WebSocket 时，请求的数据格式为 JSON
|
||
|
||
```json
|
||
{
|
||
"action": "send_private_msg", // 请求 API 端点
|
||
"params": {
|
||
// 请求参数
|
||
"user_id": 10000,
|
||
"message": "hello"
|
||
},
|
||
"echo": "123456" // 自定义的回显字段
|
||
}
|
||
```
|
||
|
||
对于 `echo` 字段，Shamrock 会在响应中原样返回。
|
||
|
||
## 响应
|
||
|
||
Shamrock 的响应格式为 JSON
|
||
|
||
```json
|
||
{
|
||
"status": "ok", // 状态，ok 为成功，其他将在下文中详细说明
|
||
"retcode": 0, // 返回码，0 为成功，非 0 为失败
|
||
"msg": "", // 错误信息，仅在 API 调用失败时出现
|
||
"wording": "", // 对错误信息的描述，仅在 API 调用失败时出现
|
||
"data": {
|
||
// 响应数据
|
||
"message_id": 123456
|
||
},
|
||
"echo": "123456" // 请求中的回显字段
|
||
}
|
||
```
|
||
|
||
### 状态
|
||
|
||
Shamrock 的响应状态有以下几种：
|
||
|
||
- `ok`：成功
|
||
- `failed`：失败
|