Merge pull request #723 from haoxiuwen/doc-v2

Add REST APIs of Deleting Messages
easemob · Apr 17, 2024 · 719769f · 719769f
2 parents e594c47 + 1378f25
commit 719769f
Show file tree

Hide file tree

Showing 5 changed files with 172 additions and 17 deletions.
diff --git a/docs/.vuepress/sidebar/document.ts b/docs/.vuepress/sidebar/document.ts
@@ -297,7 +297,7 @@ const documentSidebar = [
           { text: '上传和下载文件', link: 'message_download.html' },
           { text: '获取历史消息记录', link: 'message_historical.html' },
           { text: '撤回消息和单向删除会话', link: 'message_recall.html' },
-          { text: '单向清空漫游消息', link: 'message_roam_clear.html' },
+          { text: '单向删除漫游消息', link: 'message_delete.html' },
           { text: '修改文本或自定义消息', link: 'message_modify_text_custom.html' },
           { text: '导入消息', link: 'message_import.html' }
         ]

diff --git a/docs/document/server-side/message_roam_clear.md b/docs/document/server-side/message_roam_clear.md
@@ -1,7 +1,9 @@
-# 单向清空漫游消息
+# 删除漫游消息
 
-本文介绍如何单向清空环信服务端的漫游消息，包含以下三个 REST API：
+本文介绍如何根据消息 ID 单向删除单聊和群聊的漫游消息以及如何单向清空环信服务端的漫游消息，包含以下五个 REST API：
 
+- [根据消息 ID 单向删除单聊漫游消息](#根据消息-ID-单向删除单聊漫游消息)
+- [根据消息 ID 单向删除群聊漫游消息](#根据消息-ID-单向删除群聊漫游消息)
 - [单向清空指定用户的漫游消息](#单向清空指定用户的漫游消息)
 - [单向清空指定单聊会话一段时间内的漫游消息](#单向清空指定单聊会话一段时间内的漫游消息)
 - [单向清空指定群组或聊天室会话一段时间内的漫游消息](#单向清空指定群组或聊天室会话一段时间内的漫游消息)
@@ -31,25 +33,171 @@
 
 为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 推荐使用 app token 的鉴权方式，详见 [使用 App Token 鉴权](easemob_app_token.html)。
 
+## 根据消息 ID 单向删除单聊漫游消息
+
+根据消息 ID 单向删除指定单聊会话的一条或多条漫游消息。
+
+漫游消息删除后，当前用户无法从环信服务端拉取到这些消息。若该会话的全部漫游消息均被删除了，该用户的这个会话在服务端也会被清除，拉取会话列表时拉不到该会话。不过，其他用户不受影响，仍然可以拉取与该用户的漫游消息和会话。
+
+**调用频率上限**：100 次/秒/App Key
+
+### HTTP 请求
+
+```http
+DELETE https://{host}/{org_name}/{app_name}/rest/message/roaming/chat/user/{userId}
+```
+
+#### 路径参数
+
+| 参数              | 类型   | 是否必需 | 描述           |
+| :---------------- | :----- | :------- |:-------------|
+| `userId`  | String | 是       | 当前用户的用户 ID。  |
+
+其他参数及描述详见 [公共参数](#公共参数)。
+
+#### 请求参数
+
+| 参数      | 类型     | 是否必需 | 描述       |
+|:--------|:-------|:-----|:-------------------|
+| `userId` | String | 是    | 单聊会话中的对端用户 ID。     |
+| `msgIdList` | String | 是    | 要删除的消息的消息 ID。每次最多可传入 50 个消息 ID，消息 ID 之间以英文逗号分隔，例如 message ID 1,message ID 2。 |
+
+#### 请求 header
+
+| 参数            | 类型   | 是否必需<div style="width: 80px;"></div> | 描述     |
+| :-------------- | :----- | :----------------- | :-------------------- |
+| `Content-Type`  | String | 是                                       | 内容类型。请填 `application/json`。    |
+| `Accept`        | String | 是                                       | 内容类型。请填 `application/json`。    |
+| `Authorization` | String | 是                                       | App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。 |
+
+### HTTP 响应
+
+#### 响应 body
+
+如果返回的 HTTP 状态码为 `200`，表示请求成功，响应包体中包含以下字段：
+
+| 字段                       | 类型     | 描述         |
+|:-------------------------|:-------|:-----------|
+| `requestStatusCode`      | String | 返回 `ok` 表示消息成功删除。 |
+| `timestamp`          | Number | HTTP 响应的 Unix 时间戳，单位为毫秒。    |
+
+关于其他字段及描述，详见 [公共参数](#公共参数)。
+
+如果返回的 HTTP 状态码非 `200`，表示请求失败。你可以参考 [响应状态码](error.html) 了解可能的原因。
+
+### 示例
+
+#### 请求示例
+
+```shell
+# 将 <YourAppToken> 替换为你在服务端生成的 App Token
+curl --location --request DELETE 'https://XXXX/XXXX/XXXX/rest/message/roaming/chat/user/{XXXX}?userId={XXXX}&msgIdList=XXXX' \
+-H 'Authorization: Bearer <YourAppToken>' \
+-H 'Content-Type: application/json' \
+-H 'Accept: application/json'
+```
+
+#### 响应示例
+
+```json
+{
+  "requestStatusCode": "ok",
+  "timestamp": 1710309184114
+}
+```
+
+## 根据消息 ID 单向删除群聊漫游消息
+
+根据消息 ID 单向删除指定群聊会话的一条或多条漫游消息。
+
+漫游消息删除后，当前用户无法从环信服务端拉取到这些消息。若删除了该群聊会话的全部漫游消息，该用户的这个会话在服务端也会被清除，拉取会话列表时拉不到该会话。不过，其他用户不受影响，仍然可以拉取这些漫游消息和会话。
+
+**调用频率上限**：100 次/秒/App Key
+
+### HTTP 请求
+
+```http
+DELETE https://{host}/{org_name}/{app_name}/rest/message/roaming/group/user/{userId}
+```
+
+#### 路径参数
+
+| 参数              | 类型   | 是否必需 | 描述           |
+| :---------------- | :----- | :------- |:-------------|
+| `userId`  | String | 是       | 当前用户的用户 ID。  |
+
+其他参数及描述详见 [公共参数](#公共参数)。
+
+#### 请求参数
+
+| 参数      | 类型     | 是否必需 | 描述                                    |
+|:--------|:-------|:-----|:----------------------|
+| `groupId` | String | 是    | 群组 ID。                                 |
+| `msgIdList` | String | 是    | 要删除的消息的消息 ID。每次最多可传入 50 个消息 ID，消息 ID 之间以英文逗号分隔，例如 message ID 1,message ID 2。 |
+
+#### 请求 header
+
+| 参数            | 类型   | 是否必需<div style="width: 80px;"></div> | 描述            |
+| :-------------- | :----- | :--------------------------------------- | :-------------------- |
+| `Content-Type`  | String | 是                                       | 内容类型。请填 `application/json`。   |
+| `Accept`        | String | 是                                       | 内容类型。请填 `application/json`。    |
+| `Authorization` | String | 是                                       | App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。 |
+
+### HTTP 响应
+
+#### 响应 body
+
+如果返回的 HTTP 状态码为 `200`，表示请求成功，响应包体中包含以下字段：
+
+| 字段                       | 类型     | 描述         |
+|:-------------------------|:-------|:-----------|
+| `requestStatusCode`      | String | 返回 `ok` 表示消息成功删除。 |
+| `timestamp`          | number | HTTP 响应的 Unix 时间戳，单位为毫秒。 |
+
+其他字段及描述详见 [公共参数](#公共参数)。
+
+如果返回的 HTTP 状态码非 `200`，表示请求失败。你可以参考 [响应状态码](error.html) 了解可能的原因。
+
+### 示例
+
+#### 请求示例
+
+```shell
+# 将 <YourAppToken> 替换为你在服务端生成的 App Token
+curl --location --request DELETE 'https://XXXX/XXXX/XXXX/rest/message/roaming/group/user/XXXX?groupId=XXXX&msgIdList=XXXX' \
+-H 'Authorization: Bearer <YourAppToken>' \
+-H 'Content-Type: application/json' \
+-H 'Accept: application/json'
+```
+
+#### 响应示例
+
+```json
+{
+  "requestStatusCode": "ok",
+  "timestamp": 1710309184114
+}
+```
+
 ## 单向清空指定用户的漫游消息
 
 清空指定用户当前时间及之前的所有漫游消息。
 
 清空后，该用户无法从服务端拉取到漫游消息，而且该用户的所有会话也会被清除，也拉不到会话列表。不过，其他用户不受影响，仍然可以拉取与该用户的漫游消息和会话。
 
-**调用频率**：100 次/秒/App Key
+**调用频率上限**：100 次/秒/App Key
 
 ### HTTP 请求
 
 ```http
-POST https://{host}/{org_name}/{app_name}/rest/message/roaming/user/{username}/delete/all
+POST https://{host}/{org_name}/{app_name}/rest/message/roaming/user/{userId}/delete/all
 ```
 
 #### 路径参数
 
 | 参数       | 类型   | 是否必需 | 描述        |
 | :--------- | :----- | :------- | :----------------------- |
-| `username`  | String | 是       | 要清空哪个用户的漫游消息。需传入该用户的用户 ID。  |
+| `userId`  | String | 是       | 要清空哪个用户的漫游消息。需传入该用户的用户 ID。  |
 
 #### 请求 header
 
@@ -99,19 +247,19 @@ curl --location --request POST 'https://XXXX/XXXX/XXXX/rest/message/roaming/user
 
 清空后，该用户无法从环信服务端拉取到这些漫游消息。若清除了该会话的全部漫游消息，该用户的这个会话在服务端也会被清除，拉取会话列表时拉不到该会话。不过，其他用户不受影响，仍然可以拉取与该用户的漫游消息和会话。
 
-**调用频率**：100 次/秒/App Key
+**调用频率上限**：100 次/秒/App Key
 
 ### HTTP 请求
 
 ```http
-DELETE https://{host}/{org_name}/{app_name}/rest/message/roaming/chat/user/{username}/time?userId={userId}&delTime={delTime}
+DELETE https://{host}/{org_name}/{app_name}/rest/message/roaming/chat/user/{userId}/time?userId={userId}&delTime={delTime}
 ```
 
 #### 路径参数
 
 | 参数        | 类型   | 是否必需 | 描述           |
 | :--------- | :----- | :------- |:-------------|
-| `username`  | String | 是       | 调用该接口的用户的用户 ID。 |
+| `userId`  | String | 是       | 调用该接口的用户的用户 ID。 |
 | `userId` | String | 是       | 要清空与哪个用户的单聊会话的漫游消息。需传入该用户的用户 ID。  |
 | `delTime`  | Long | 是       | 要清空哪个时间点及之前的单聊漫游消息。该时间为 Unix 时间戳，单位为毫秒。 |
 
@@ -165,19 +313,19 @@ curl --location --request DELETE 'http://XXXX/XXXX/XXXX/rest/message/roaming/cha
 
 清空后，该用户无法从环信服务端拉取到这些漫游消息。若清除了该会话的全部漫游消息，该用户的这个会话在服务端也会被清除，拉取会话列表时拉不到该会话。不过，其他用户不受影响，仍然可以拉取这些漫游消息和会话。
 
-**调用频率**：100 次/秒/App Key
+**调用频率上限**：100 次/秒/App Key
 
 ### HTTP 请求
 
 ```http
-DELETE https://{host}/{org_name}/{app_name}/rest/message/roaming/group/user/{username}/time?groupId={groupId}&delTime={delTime}
+DELETE https://{host}/{org_name}/{app_name}/rest/message/roaming/group/user/{userId}/time?groupId={groupId}&delTime={delTime}
 ```
 
 #### 路径参数
 
 | 参数        | 类型   | 是否必需 | 描述           |
 | :--------- | :----- | :------- |:-------------|
-| `username`  | String | 是   | 调用该接口的用户的用户 ID。  |
+| `userId`  | String | 是   | 调用该接口的用户的用户 ID。  |
 | `groupId` | String  | 是    | 要清空哪个群组或聊天室的漫游消息。你可以传入群组 ID 或聊天室 ID。|
 | `delTime` | Long  | 是    | 要清空哪个时间点及之前的群组或聊天室的漫游消息。该时间为 Unix 时间戳，单位为毫秒。 |
 

diff --git a/docs/document/server-side/presence.md b/docs/document/server-side/presence.md
@@ -103,7 +103,12 @@ curl -X POST 'a1-test.easemob.com:8089/5101220107132865/test/users/c1/presence/a
 
 ## 批量订阅在线状态
 
-一次可订阅多个用户的在线状态。
+一次可订阅多个用户的在线状态。批量订阅用户在线状态分为同步订阅和异步订阅：
+- 同步订阅：服务器会首先订阅用户在线状态，然后返回该 API 的响应，这样可以保证实时获取到订阅用户在线状态列表。
+  如果订阅用户的数量小于 5 人，默认为同步订阅。
+
+- 异步订阅：服务器会首先将订阅用户在线状态的任务放到队列中，然后返回该 API 的响应，不能保证能实时获取到订阅用户在线状态列表。
+  如果订阅的用户数量大于 5 人，默认为异步订阅。如需要同步订阅，可以联系环信商务进行开通。
 
 ### HTTP 请求
 

diff --git a/docs/product/limitationapi.md b/docs/product/limitationapi.md
@@ -64,9 +64,11 @@
 | 服务端消息撤回    |    POST  | /{org_name}/{app_name}/messages/recall        | 100 次/秒/App Key                                                 |
 | 服务端单向删除会话   |    DELETE    | /{org_name}/{app_name}/users/{userName}/user_channel          | 5 次/分钟/单用户 ID，100 次/秒/App Key                                              |
 | 修改文本或自定义消息 | PUT  | /{org_name}/{app_name}/messages/rewrite/{msg_id} | 100 次/秒/App Key  |
-| 单向清空指定用户的漫游消息 | POST  | /{org_name}/{app_name}/rest/message/roaming/user/{username}/delete/all | 100 次/秒/App Key  |
-| 单向清空指定单聊会话一段时间内的漫游消息 | POST  | /{org_name}/{app_name}/rest/message/roaming/chat/user/{username}/time?userId={userId}&delTime={delTime} | 100 次/秒/App Key  |
-| 单向清空指定群组或聊天室会话一段时间内的漫游消息 | POST  | /{org_name}/{app_name}/rest/message/roaming/group/user/{username}/time?groupId={groupId}&delTime={delTime} | 100 次/秒/App Key  |
+| 根据消息 ID 单向删除单聊漫游消息  | DELETE    | /{org_name}/{app_name}/rest/message/roaming/chat/user/{userId}    | 100 次/秒/App Key   |
+| 根据消息 ID 单向删除群聊漫游消息  | DELETE    | /{org_name}/{app_name}/rest/message/roaming/group/user/{userId}    | 100 次/秒/App Key   |
+| 单向清空指定用户的漫游消息 | POST  | /{org_name}/{app_name}/rest/message/roaming/user/{userId}/delete/all | 100 次/秒/App Key  |
+| 单向清空指定单聊会话一段时间内的漫游消息 | POST  | /{org_name}/{app_name}/rest/message/roaming/chat/user/{userId}/time?userId={userId}&delTime={delTime} | 100 次/秒/App Key  |
+| 单向清空指定群组或聊天室会话一段时间内的漫游消息 | POST  | /{org_name}/{app_name}/rest/message/roaming/group/user/{userId}/time?groupId={groupId}&delTime={delTime} | 100 次/秒/App Key  |
 | 导入单聊消息 | POST  | /{org_name}/{app_name}/messages/users/import | 100 条/秒/App Key                                          |
 | 导入群聊消息 | POST  | /{org_name}/{app_name}/messages/chatgroups/import | 100 条/秒/App Key                                    |
 | 拉取会话列表    |   GET    | /{org_name}/{app_name}/user/{username}/user_channels       | 5 次/分钟/单用户 ID，100 次/秒/App Key    |

diff --git a/docs/product/product_dynamics.md b/docs/product/product_dynamics.md
@@ -5,7 +5,7 @@
 | 动态名称   | 动态描述 | 发布时间       | 相关文档          |
 | :----- | :------- | :---------------- | :---------------- |
 | SDK 4.5.0 开发版发布  | **新增特性**：<br/> - 客户端可[置顶消息](/document/android/message_pin.html)，方便会话中的所有用户快速查看重要消息。<br/> - 客户端的消息修改回调中可返回[通过 RESTful API 修改的自定义消息](/document/server-side/message_modify_text_custom.html)。<br/> - 客户端加入聊天室时，若传入的聊天室 ID 不存在，可实现[自动创建聊天室](/document/android/room_manage.html#加入聊天室)。若使用该功能，你需要联系商务开通。<br/> - 客户端支持[获取聊天室漫游消息](/document/android/message_retrieve.html#从服务器获取指定会话的历史消息)。若使用该功能，你需要联系商务开通。<br/> - Android 端 SDK 集成支持[动态加载 .so 库文件](/document/android/quickstart.html#方法三-动态加载-so-库文件)，减少应用安装包的大小。<br/> - iOS 端可[将所有会话的未读消息设为已读](/document/ios/conversation_unread.html#将所有会话的未读消息数清零)，将所有会话的未读消息数清零。<br/>**优化**：<br/> - 优化 token 登录时的错误提示信息，使错误提示更准确。<br/> - 移动端优化[单条转发](/document/android/message_forward.html)功能，附件消息无需重新上传附件即可转发。 |  2024-04-03    |  <br/> - [Android 4.5.0 更新日志](/document/android/releasenote.html#版本-v4-5-0-dev-2024-04-03-开发版)<br/> - [iOS 4.5.0 更新日志](/document/ios/releasenote.html#版本-v4-5-0-dev-2024-04-03-开发版)<br/> - [Web 4.6.0 更新日志](/document/web/releasenote.html#版本-v4-6-0-dev-2024-04-02-开发版)<br/> - [小程序 4.6.0 更新日志](/document/applet/releasenote.html#版本-v4-6-0-dev-2024-04-02-开发版)。|
-| REST API |**新增 API**： <br/> 1. [分页获取好友列表](/document/server-side/user_relationship.html#分页获取好友列表)；<br/> 2. [单向清空漫游消息](/document/server-side/message_roam_clear.html)：[根据时间单向清空单聊会话的漫游消息](/document/server-side/message_roam_clear.html#单向清空指定单聊会话一段时间内的漫游消息)；[根据时间单向清空群组或聊天室会话的漫游消息](/document/server-side/message_roam_clear.html#单向清空指定群组或聊天室会话一段时间内的漫游消息)；[清空用户的所有漫游消息](/document/server-side/message_roam_clear.html#单向清空指定用户的漫游消息)；<br/> 3. [修改文本或自定义消息](/document/server-side/message_modify_text_custom.html)；<br/> 4. [转让聊天室](/document/server-side/chatroom.html#转让聊天室)；<br/> 5. [强制指定账号从单设备下线](/document/server-side/account_system.html#强制用户从单设备下线)。| 2024-04 | 关于接口的调用频率限制，详见 [API 调用频率限制](/document/server-side/limitationapi.html)。 |
+| REST API |**新增 API**： <br/> 1. [分页获取好友列表](/document/server-side/user_relationship.html#分页获取好友列表)；<br/> 2. [单向清空漫游消息](/document/server-side/message_delete.html)：[根据时间单向清空单聊会话的漫游消息](/document/server-side/message_delete.html#单向清空指定单聊会话一段时间内的漫游消息)；[根据时间单向清空群组或聊天室会话的漫游消息](/document/server-side/message_delete.html#单向清空指定群组或聊天室会话一段时间内的漫游消息)；[清空用户的所有漫游消息](/document/server-side/message_delete.html#单向清空指定用户的漫游消息)；<br/> 3. [修改文本或自定义消息](/document/server-side/message_modify_text_custom.html)；<br/> 4. [转让聊天室](/document/server-side/chatroom.html#转让聊天室)；<br/> 5. [强制指定账号从单设备下线](/document/server-side/account_system.html#强制用户从单设备下线)。| 2024-04 | 关于接口的调用频率限制，详见 [API 调用频率限制](/document/server-side/limitationapi.html)。 |
 
 ## 2024-01