设置指定消息附件的存储方式
大约 4 分钟
REST API
设置指定消息附件的存储方式
环信服务器支持对用户指定的消息附件设置存储方式,可延长存储时间或实现永久存储,支持通过客户端和 RESTful API 发送图片、语音、视频、文件消息和合并消息时上传的附件(包括图片和视频的缩略图)。
对于永久存储的消息附件,用户可以随时获取这些附件。
提示
若使用该接口,需联系环信商务开通。
调用频率:100 次/秒/App Key
HTTP 请求
POST https://{host}/{org_name}/{app_name}/users/{username}/chatfiles/lifetime
路径参数
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
username | String | 是 | 调用该接口的用户 ID。 |
其他参数及说明详见 公共参数。
请求 Header
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
Content-Type | String | 是 | 内容类型。请填 application/json 。 |
Accept | String | 是 | 内容类型。请填 application/json 。 |
Authorization | String | 是 | App 管理员的鉴权 token,格式为 Bearer YourAppToken ,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。 |
请求 body
参数 | 类型 | 是否必需 | 描述 |
---|---|---|---|
lifetime | String | 是 | 消息附件保存时间: - (默认) default :配置的消息附件的默认有效期;- refresh :刷新消息附件的有效期,相当于重新设置存储时间,延长了存储时长。例如,消息附件可存储 7 天,在存储的第五天时调用了该接口,即将附件的存储时间设置为 7 天,则附件的剩余存储时间为 7 天。该设置可用于延长合并消息的附件存储时间,例如,发送合并消息时,原始图片的存储时间只剩余 1 天,调用该接口时利用该设置可将存储时间延长。- forever :永久有效。 |
chatfile_ids | Array | 是 | 消息附件的文件 UUID,最多可传入 100 个。 |
HTTP 响应
响应 body
如果返回的 HTTP 状态码为 200
,表示请求成功,响应包体中包含以下字段:
参数 | 类型 | 描述 |
---|---|---|
path | String | 请求路径,属于请求 URL 的一部分,开发者无需关注。 |
uri | String | 请求 URL。 |
timestamp | Long | HTTP 响应的 Unix 时间戳,单位为毫秒。 |
organization | String | 环信即时通讯 IM 为每个公司(组织)分配的唯一标识,与请求参数 org_name 相同。 |
application | String | 系统内为应用生成的唯一标识,开发者无需关心。 |
action | String | 请求方法。 |
data | JSON | 是否成功设置消息附件的存储: - success :成功;- failed :失败。 |
duration | Long | 从发送 HTTP 请求到响应的时长, 单位为毫秒。 |
applicationName | String | 你在环信即时通讯云控制台创建应用时填入的应用名称,与请求参数 app_name 相同。 |
响应字段及说明详见 公共参数。
如果返回的 HTTP 状态码非 200
,表示请求失败。你可以参考 错误码了解可能的原因。
示例
请求示例
# 将 <YourUserToken> 替换为你的用户 Token
curl -X PUT -L "http://localhost/{org}/{app}/users/{username}/chatfiles/lifetime" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <YourUserToken>" \
-d '{
"lifetime": "default",
"chatfile_ids": [
"2fe7f0b0-0b55-XXXX-XXXX-231441e42458"
]
}'
响应示例
{
"path": "/users/test/chatfiles/lifetime",
"uri": "https://XXXX/XXXX/XXXX/users/test/chatfiles/lifetime",
"timestamp": 1731382587142,
"organization": "XXXX",
"application": "2a8f5b13-XXXX-XXXX-958a-838fd47f1223",
"action": "put",
"data": {
"359f9c50-XXXX-XXXX-92cd-07eff71e8a37": "success"
},
"duration": 102,
"applicationName": "XXXX"
}
错误码
如果返回的 HTTP 状态码非 200
,表示请求失败,可能提示以下错误码:
HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 |
---|---|---|---|---|
403 | forbidden_op | 设置消息附件存储的功能未开通。 | 联系环信商务开通该功能。 | |
400 | illegal_argument | chatfile_ids size is too large | 请求中传入的消息附件的文件 ID chatfile_ids 超过了上限 100. | 消息附件的文件 ID 最多可传 100 个。 |
400 | illegal_argument | lifetime must be either 'forever' or 'default' or 'refresh'。 | 消息附件保存时间 lifetime 传入了 forever 、default 或 refresh 之外的值。 | 消息附件保存时间 lifetime 只能设置为 forever 、default 或 refresh ,不能传入其他值。 |
401 | unauthorized | Unable to authenticate (OAuth) | token 不合法,可能过期或 token 错误。 | 使用新的 token 访问。 |
关于其他错误,你可以参考 错误码 了解可能的原因。