M4 HTTP 和 WebSocket 接口文档
输入“/”快速插入内容
M4 HTTP 和 WebSocket 接口文档
M4 HTTP 和 WebSocket 接口文档
飞书用户9090飞书用户3398
飞书用户5179飞书用户1983飞书用户6079+8
8月11日修改
1.1 概述
M4 对外提供多种协议的接口。本文档主要讨论 HTTP 和 WebSocket 接口。
1.1.1 HTTP 风格概述
M4 的 HTTP 接口多数的请求和响应正文是 JSON （application/json）。并且根据 HTTP 规范，一定是 UTF-8 编码的（即 application/json; charset=utf-8）。
HTTP 接口参考了 Restful 风格。但考虑到国内的接受程度，未能全面采用 Restful 风格。比如还是尽量使用了 GET 和 POST 请求，少用 PUT/DELETE 请求。
但在 HTTP 响应码上，一般：
•
200 表示请求成功。
•
201 现在已尽量避免使用 201。规范含义是创建成功。但现在尽量都尽量改用 200。
•
400 表示请求错误（Bad Request）。
•
404 表示请求的 URL 不存在。
•
401 表示身份验证失败（未登录）。
•
403 表示已登录但权限不够。
•
500 表示服务器内部错误，即服务器出 BUG 了。
•
502 表示服务不可用。
•
504 表示请求超时。
对于 400，即请求错误。响应正文是一个 JSON。有 code 和 message 两个字段，给出错误码和错误消息。code 可能为空，但 message 一定有内容。
代码块
{ "code": "NoSuchRobot", "message": "找不到机器人 '2032'" }
1.1.2 时间
为了方便各语音解析，接口返回的日期时间字段，一般是一个 Unix timestamp 长整数，毫秒精度，如 1699200000000。注意需要一个 8 字节整数才能表示。
请求中的日期时间，我们会“尽力解析”，包括 ISO 8601 等。目前支持以下格式：
"yyyy-MM-dd'T'HH:mm:ss.SSSXXX",
"yyyy-MM-dd'T'HH:mm:ss.SSSZ",
"yyyy-MM-dd'T'HH:mm:ssX",
"yyyy-MM-dd HH:mm:ss",
"yyyy-MM-dd HH:mm:ss.SSS",
"yyyy-MM-dd HH:mm",
"yyyy-MM-dd",
"yyyy/MM/dd",
"HH:mm:ss"
1.2 安全相关接口
1.2.1 PING 接口
GET /api/ping
用来检查是否能与服务器通讯并且处于已登录状态。如果未登录（或过期）返回 401。如果已登录，返回用户 ID、用户名等信息。如
代码块
{
"id": "__admin__",
"username": "admin",
"roAdmin": true,
"permissions": null
}
1.2.2 登录接口
POST /api/sign-in
请求正文，携带用户名和密码，如：
代码块
{
"username": "admin",
"password": "admin"
}