|
| 1 | +# 单向删除会话 |
| 2 | + |
| 3 | +你可以从服务器中单向删除会话，并且设置是否删除该会话在服务端的漫游消息。删除会话后，该用户将从服务器获取不到该会话。该会话的其他参与聊天用户仍然可以从服务器获取会话内容。 |
| 4 | + |
| 5 | +## 前提条件 |
| 6 | + |
| 7 | +要调用声网即时通讯 RESTful API，请确保满足以下要求： |
| 8 | + |
| 9 | +- 已在[声网控制台](https://console.shengwang.cn/overview) [开通配置声网即时通讯 IM 服务](enable_im.html)。 |
| 10 | +- 已从服务端获取 app token，详见 [使用 Token 鉴权](token_authentication.html)。 |
| 11 | +- 了解声网即时通讯 IM API 的调用频率限制，详见 [接口频率限制](limitationapi.html)。 |
| 12 | + |
| 13 | +## 认证方式 |
| 14 | + |
| 15 | +声网即时通讯 IM RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 `Authorization` 字段： |
| 16 | + |
| 17 | +`Authorization: Bearer YourAppToken` |
| 18 | + |
| 19 | +为提高项目的安全性，声网使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 RESTful API 推荐使用 app token 的 鉴权方式，详见 [使用 Token 鉴权](token_authentication.html)。 |
| 20 | + |
| 21 | +## HTTP 请求 |
| 22 | + |
| 23 | +```http |
| 24 | +DELETE https://{host}/app-id/{app_id}/users/{username}/user_channel |
| 25 | +``` |
| 26 | + |
| 27 | +#### 路径参数 |
| 28 | + |
| 29 | +| 参数 | 类型 | 是否必需 | 描述 | |
| 30 | +| :--------- | :----- | :------- | :------------------------- | |
| 31 | +| `host` | String | 是 | 即时通讯 IM 分配的用于访问 RESTful API 的域名。 | |
| 32 | +| `app_id` | String | 是 | 声网为每个项目自动分配的 App ID，作为项目唯一标识。 | |
| 33 | +| `username` | String | 是 | 要删除会话的用户的唯一标识符，即用户 ID。 | |
| 34 | + |
| 35 | +#### 请求 header |
| 36 | + |
| 37 | +| 参数 | 类型 | 是否必需 | 描述 | |
| 38 | +| :-------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------- | |
| 39 | +| `Authorization` | String | 是 | App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。 | |
| 40 | + |
| 41 | +#### 请求 body |
| 42 | + |
| 43 | +| 参数 | 类型 | 是否必需 | 描述 | |
| 44 | +| :------------ | :----- | :------- | :------------------------- | |
| 45 | +| `channel` | String | 是 | 要删除的会话 ID。该参数的值取决于会话类型 `type` 的值:<br/> - `type` 为 `chat`，即单聊时，会话 ID 为对端用户 ID；<br/> - `type` 为 `groupchat`，即群聊时，会话 ID 为群组 ID。 | |
| 46 | +| `type` | String | 是 | 会话类型。<br/> - `chat`：单聊会话；<br/> -`groupchat`：群聊会话。 | |
| 47 | +| `delete_roam` | Bool | 是 | 是否删除该会话在服务端的漫游消息。<br/> - `true`：是。若删除了该会话的服务端消息，则用户无法从服务器拉取该会话的漫游消息。<br/> - `false`：否。用户仍可以从服务器拉取该会话的漫游消息。 | |
| 48 | + |
| 49 | +## HTTP 响应 |
| 50 | + |
| 51 | +#### 响应 body |
| 52 | + |
| 53 | +如果返回的 HTTP 状态码为 `200`，表示请求成功，响应包体中包含以下字段： |
| 54 | + |
| 55 | +| 参数 | 类型 | 描述 | |
| 56 | +| :---------------- | :----- | :---------------------------- | |
| 57 | +| `path` | String | 请求路径，属于请求 URL 的一部分，开发者无需关注。 | |
| 58 | +| `uri` | String | 请求 URL。 | |
| 59 | +| `timestamp` | Long | HTTP 响应的 Unix 时间戳，单位为毫秒。 | |
| 60 | +| `entities` | JSON | 响应实体。 | |
| 61 | +| `action` | String | 请求方法。 | |
| 62 | +| `data` | JSON | 删除结果详情。 | |
| 63 | +| `data.result` | String | 删除结果，`ok` 表示成功，失败则直接返回错误码和原因。 | |
| 64 | +| `duration` | Int | 从发送 HTTP 请求到响应的时长，单位为毫秒。 | |
| 65 | +如果返回的 HTTP 状态码非 `200`，表示请求失败。你可以参考 [响应状态码](error.html) 了解可能的原因。 |
| 66 | + |
| 67 | +## 示例 |
| 68 | + |
| 69 | +#### 请求示例 |
| 70 | + |
| 71 | +```shell |
| 72 | +# 将 <YourAppToken> 替换为你在服务端生成的 App Token |
| 73 | + |
| 74 | +curl -L -X DELETE 'https://XXXX/app-id/XXXX/users/u1/user_channel' \ |
| 75 | +-H 'Authorization: Bearer <YourAppToken>' \ |
| 76 | +-H 'Content-Type: application/json' \ |
| 77 | +-H 'Accept: application/json' \ |
| 78 | +-d '{ |
| 79 | + "channel": "u2", |
| 80 | + "type": "chat", |
| 81 | + "delete_roam": true |
| 82 | + }' |
| 83 | +``` |
| 84 | + |
| 85 | +#### 响应示例 |
| 86 | + |
| 87 | +```json |
| 88 | +{ |
| 89 | + "path": "/users/user_channel", |
| 90 | + "uri": "https://XXXX/XXXX/XXXX/users/u1/user_channel", |
| 91 | + "timestamp": 1638440544078, |
| 92 | + "entities": [], |
| 93 | + "action": "delete", |
| 94 | + "data": { |
| 95 | + "result": "ok" |
| 96 | + }, |
| 97 | + "duration": 3 |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +## 错误码 |
| 102 | + |
| 103 | +如果返回的 HTTP 状态码非 `200`，表示请求失败，可能提示以下错误码： |
| 104 | + |
| 105 | +| HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 | |
| 106 | +|:---------|:-------------------|:----------------------|:-----------------|:----------| |
| 107 | +| 400 | invalid_request_body | Request body is invalid. Please check body is correct. | 请求体格式不正确。 | 检查请求体内容是否合法(字段类型是否正确) 。 | |
| 108 | +| 400 | illegal_argument | field channel cannot be null or empty | 请求参数 `channel` 是空字符串 | 输入正确的请求参数 `channel`。| |
| 109 | +| 400 | illegal_argument | field type cannot be null or empty | 请求参数 `type` 是空字符串。 | 输入正确的请求参数 `type`。 | |
| 110 | +| 400 | illegal_argument | field delete_roam cannot be null | 请求参数 `delete_roam` 是空。 | 输入正确的请求参数`delete_roam`。 | |
| 111 | + |
| 112 | +关于其他错误，你可以参考 [响应状态码](error.html) 了解可能的原因。 |
0 commit comments