Skip to content

Commit e87f3f7

Browse files
haoxiuwenhaoxiuwen
authored
Merge pull request #1036 from haoxiuwen/doc-v2
Add the RESTful API of Setting the Restoration Way of Message Attachments
2 parents 539d5a9 + 0f35cd4 commit e87f3f7

File tree

3 files changed

+111
-0
lines changed

3 files changed

+111
-0
lines changed

‎docs/.vuepress/sidebar/document.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -340,6 +340,7 @@ const documentSidebar = [
340340
{ text: '发送聊天室消息', link: 'message_chatroom.html' },
341341
{ text: '上传和下载文件', link: 'message_download.html' },
342342
{ text: '获取历史消息记录', link: 'message_historical.html' },
343+
{ text: '设置指定消息附件的存储方式', link: 'message_attachment_storage.html' },
343344
{ text: '撤回消息和单向删除会话', link: 'message_recall.html' },
344345
{ text: '单向删除漫游消息', link: 'message_delete.html' },
345346
{ text: '修改文本或自定义消息', link: 'message_modify_text_custom.html' },

‎docs/document/server-side/message_attachment_storage.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# 设置指定消息附件的存储方式
2+
3+
环信服务器支持对用户指定的消息附件设置存储方式，可延长存储时间或实现永久存储，支持通过客户端和 RESTful API 发送图片、语音、视频、文件消息和合并消息时上传的附件（包括图片和视频的缩略图）。
4+
5+
对于永久存储的消息附件，用户可以随时获取这些附件。
6+
7+
:::tip
8+
若使用该接口，需联系环信商务开通。
9+
:::
10+
11+
**调用频率**：100 次/秒/App Key
12+
13+
#### HTTP 请求
14+
15+
```http
16+
POST https://{host}/{org_name}/{app_name}/users/{username}/chatfiles/lifetime
17+
```
18+
19+
##### 路径参数
20+
21+
| 参数 | 类型 | 是否必需 | 描述 |
22+
| :--------- | :----- | :------- | :------------------------- |
23+
| `username` | String | 是 | 调用该接口的用户 ID。 |
24+
25+
其他参数及说明详见 [公共参数](#公共参数)。
26+
27+
##### 请求 Header
28+
29+
| 参数 | 类型 | 是否必需 | 描述 |
30+
| :------------- | :----- | :------- | :---------------------------------- |
31+
| `Content-Type` | String | 是 | 内容类型。请填 `application/json`。 |
32+
| `Accept` | String | 是 | 内容类型。请填 `application/json`。 |
33+
| `Authorization` | String | 是 | App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。 |
34+
35+
##### 请求 body
36+
37+
| 参数 | 类型 | 是否必需 | 描述 |
38+
| :--------- | :----- | :------- | :-------------------------------------------- |
39+
| `lifetime` | String | 是 | 消息附件保存时间：<br/> - （默认）`default`：配置的消息附件的默认有效期；<br/> - `refresh`：刷新消息附件的有效期，相当于重新设置存储时间，延长了存储时长。例如，消息附件可存储 7 天，在存储的第五天时调用了该接口，即将附件的存储时间设置为 7 天，则附件的剩余存储时间为 7 天。该设置可用于延长合并消息的附件存储时间，例如，发送合并消息时，原始图片的存储时间只剩余 1 天，调用该接口时利用该设置可将存储时间延长。<br/> - `forever`：永久有效。 |
40+
| `chatfile_ids` | Array | 是 | 消息附件的文件 UUID，最多可传入 100 个。 |
41+
42+
#### HTTP 响应
43+
44+
##### 响应 body
45+
46+
如果返回的 HTTP 状态码为 `200`，表示请求成功，响应包体中包含以下字段：
47+
48+
| 参数 | 类型 | 描述 |
49+
| :------------------- | :----- | :-------------------------------------------- |
50+
| `path` | String | 请求路径，属于请求 URL 的一部分，开发者无需关注。 |
51+
| `uri` | String | 请求 URL。 |
52+
| `timestamp` | Long | HTTP 响应的 Unix 时间戳，单位为毫秒。 |
53+
| `organization` | String | 环信即时通讯 IM 为每个公司（组织）分配的唯一标识，与请求参数 `org_name` 相同。 |
54+
| `application` | String | 系统内为应用生成的唯一标识，开发者无需关心。 |
55+
| `action` | String | 请求方法。 |
56+
| `data` | JSON | 是否成功设置消息附件的存储：<br/> - `success`：成功；<br/> - `failed`：失败。 |
57+
| `duration` | Long | 从发送 HTTP 请求到响应的时长, 单位为毫秒。 |
58+
| `applicationName` | String | 你在环信即时通讯云控制台创建应用时填入的应用名称，与请求参数 `app_name` 相同。 |
59+
60+
响应字段及说明详见 [公共参数](#公共参数)。
61+
62+
如果返回的 HTTP 状态码非 `200`，表示请求失败。你可以参考 [错误码](#错误码)了解可能的原因。
63+
64+
#### 示例
65+
66+
##### 请求示例
67+
68+
```shell
69+
# 将 <YourUserToken> 替换为你的用户 Token
70+
curl -X PUT -L "http://localhost/{org}/{app}/users/{username}/chatfiles/lifetime" \
71+
-H "Content-Type: application/json" \
72+
-H "Authorization: Bearer <YourUserToken>" \
73+
-d '{
74+
"lifetime": "default",
75+
"chatfile_ids": [
76+
"2fe7f0b0-0b55-XXXX-XXXX-231441e42458"
77+
]
78+
}'
79+
```
80+
81+
##### 响应示例
82+
83+
```json
84+
{
85+
"path": "/users/test/chatfiles/lifetime",
86+
"uri": "https://XXXX/XXXX/XXXX/users/test/chatfiles/lifetime",
87+
"timestamp": 1731382587142,
88+
"organization": "XXXX",
89+
"application": "2a8f5b13-XXXX-XXXX-958a-838fd47f1223",
90+
"action": "put",
91+
"data": {
92+
"359f9c50-XXXX-XXXX-92cd-07eff71e8a37": "success"
93+
},
94+
"duration": 102,
95+
"applicationName": "XXXX"
96+
}
97+
```
98+
#### 错误码
99+
100+
如果返回的 HTTP 状态码非 `200`，表示请求失败，可能提示以下错误码：
101+
102+
| HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
103+
| :----------- | :--- | :------------- | :----------- | :----------- |
104+
| 403 | forbidden_op | | 设置消息附件存储的功能未开通。 | 联系环信商务开通该功能。 |
105+
| 400 | illegal_argument | chatfile_ids size is too large | 请求中传入的消息附件的文件 ID `chatfile_ids` 超过了上限 100. | 消息附件的文件 ID 最多可传 100 个。|
106+
| 400 | illegal_argument | lifetime must be either 'forever' or 'default' or 'refresh'。 | 消息附件保存时间 `lifetime` 传入了 `forever`、`default` 或 `refresh` 之外的值。 | 消息附件保存时间 `lifetime` 只能设置为 `forever`、`default` 或 `refresh`，不能传入其他值。 |
107+
| 401 | unauthorized | Unable to authenticate (OAuth) | token 不合法，可能过期或 token 错误。 | 使用新的 token 访问。 |
108+
109+
关于其他错误，你可以参考 [错误码](error.html) 了解可能的原因。

‎docs/product/limitationapi.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@
7373
| 上传文件 | POST | /{org_name}/{app_name}/chatfiles | 100 次/秒/App Key |
7474
| 下载文件 | GET | /{org_name}/{app_name}/chatfiles/{file_uuid} | 100 次/秒/App Key |
7575
| * 获取历史消息（聊天记录）文件 | GET | /{org_name}/{app_name}/chatmessages/${time} | 10 次/分钟/App Key |
76+
| * 设置指定消息附件的存储方式 | POST | /{org_name}/{app_name}/users/{username}/chatfiles/lifetime | 100 次/秒/App Key |
7677
| * 服务端消息撤回 | POST | /{org_name}/{app_name}/messages/recall | 100 次/秒/App Key |
7778
| 服务端单向删除会话 | DELETE | /{org_name}/{app_name}/users/{userName}/user_channel | 5 次/分钟/单用户 ID，100 次/秒/App Key |
7879
| 修改文本或自定义消息 | PUT | /{org_name}/{app_name}/messages/rewrite/{msg_id} | 100 次/秒/App Key |

0 commit comments

Comments
 (0)