|
| 1 | +# 获取用户离线消息数据 |
| 2 | + |
| 3 | +你可以获取单个用户的离线消息数量，以及查看该用户单个离线消息的投递状态。 |
| 4 | + |
| 5 | +## 公共参数 |
| 6 | + |
| 7 | +以下表格列举了环信 IM 的 RESTful 接口的公共请求参数和响应参数： |
| 8 | + |
| 9 | +### 请求参数 |
| 10 | + |
| 11 | +| 参数 | 类型 | 是否必需 | 描述 | |
| 12 | +| :--------- | :----- | :------- | :------------------------- | |
| 13 | +| `host` | String | 是 | 环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。 | |
| 14 | +| `org_name` | String | 是 | 环信即时通讯 IM 为每个公司（组织）分配的唯一标识。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。 | |
| 15 | +| `app_name` | String | 是 | 你在环信即时通讯云控制台创建应用时填入的应用名称。详见 [获取环信即时通讯 IM 的信息](enable_and_configure_IM.html#获取环信即时通讯-im-的信息)。 | |
| 16 | + |
| 17 | +### 响应参数 |
| 18 | + |
| 19 | +| 参数 | 类型 | 描述 | |
| 20 | +| :------------------- | :----- | :-------------------------------------------- | |
| 21 | +| `action` | String | 请求方法。 | |
| 22 | +| `uri` | String | 请求 URL。 | |
| 23 | +| `path` | String | 请求路径，属于请求 URL 的一部分，开发者无需关注。 | |
| 24 | +| `entities` | JSON Array | 响应实体。 | |
| 25 | +| `data` | JSON | 实际获取的数据详情。 | |
| 26 | +| `timestamp` | Long | HTTP 响应的 Unix 时间戳，单位为毫秒。 | |
| 27 | +| `duration` | Long | 从发送 HTTP 请求到响应的时长, 单位为毫秒。 | |
| 28 | + |
| 29 | +## 前提条件 |
| 30 | + |
| 31 | +要调用环信即时通讯 RESTful API，请确保满足以下要求： |
| 32 | + |
| 33 | +- 已在环信即时通讯云控制台 [开通配置环信即时通讯 IM 服务](enable_and_configure_IM.html)。 |
| 34 | +- 已从服务端获取 app token，详见 [使用 App Token 鉴权](easemob_app_token.html)。 |
| 35 | +- 了解环信 IM API 的调用频率限制，详见 [接口频率限制](limitationapi.html)。 |
| 36 | + |
| 37 | +## 认证方式 |
| 38 | + |
| 39 | +环信即时通讯 REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 `Authorization` 字段： |
| 40 | + |
| 41 | +`Authorization: Bearer YourAppToken` |
| 42 | + |
| 43 | +为提高项目的安全性，环信使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。本文介绍的即时通讯所有 REST API 均需使用 App Token 的鉴权方式，详见 [使用 App Token 鉴权](easemob_app_token.html)。 |
| 44 | + |
| 45 | +## 获取用户离线消息数量 |
| 46 | + |
| 47 | +获取环信 IM 用户的离线消息数量。 |
| 48 | + |
| 49 | +#### HTTP 请求 |
| 50 | + |
| 51 | +```http |
| 52 | +GET https://{host}/{org_name}/{app_name}/users/{owner_username}/offline_msg_count |
| 53 | +``` |
| 54 | + |
| 55 | +##### 路径参数 |
| 56 | + |
| 57 | +| 参数 | 类型 | 是否必需 | 描述 | |
| 58 | +| :--------------- | :----- | :------- | :---------------------------- | |
| 59 | +| `owner_username` | String | 是 | 要获取离线消息数量的用户 ID。 | |
| 60 | + |
| 61 | +其他参数及说明详见 [公共参数](#公共参数)。 |
| 62 | + |
| 63 | +##### 请求 header |
| 64 | + |
| 65 | +| 参数 | 类型 | 是否必需 | 描述 | |
| 66 | +| :-------------- | :----- | :------- | :-------------------------- | |
| 67 | +| `Accept` | String | 是 | 内容类型。请填 `application/json`。 | |
| 68 | +| `Authorization` | String | 是 | App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。 | |
| 69 | + |
| 70 | +#### HTTP 响应 |
| 71 | + |
| 72 | +##### 响应 body |
| 73 | + |
| 74 | +如果返回的 HTTP 状态码为 `200`，表示请求成功，响应包体中包含以下字段： |
| 75 | + |
| 76 | +| 字段 | 类型 | 描述 | |
| 77 | +| :----- | :--- | :------------------------------------------------------------------------------------ | |
| 78 | +| `data` | JSON | 用户的离线消息数量。数据格式为："用户 ID": "当前离线消息的数量"，例如，"user1": "0"。 | |
| 79 | + |
| 80 | +其他字段及说明详见 [公共参数](#公共参数)。 |
| 81 | + |
| 82 | +如果返回的 HTTP 状态码非 `200`，表示请求失败。你可以参考 [错误码](#错误码) 了解可能的原因。 |
| 83 | + |
| 84 | +#### 示例 |
| 85 | + |
| 86 | +##### 请求示例 |
| 87 | + |
| 88 | +```shell |
| 89 | +# 将 <YourAppToken> 替换为你在服务端生成的 App Token |
| 90 | + |
| 91 | +curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users/user1/offline_msg_count' |
| 92 | +``` |
| 93 | + |
| 94 | +##### 响应示例 |
| 95 | + |
| 96 | +```json |
| 97 | +{ |
| 98 | + "action": "get", |
| 99 | + "uri": "https://XXXX/XXXX/XXXX/users/user1/offline_msg_count", |
| 100 | + "entities": [], |
| 101 | + "data": { |
| 102 | + "user1": 0 |
| 103 | + }, |
| 104 | + "timestamp": 1542601518137, |
| 105 | + "duration": 3, |
| 106 | + "count": 0 |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +#### 错误码 |
| 111 | + |
| 112 | +如果返回的 HTTP 状态码非 `200`，表示请求失败，可能提示以下错误码： |
| 113 | + |
| 114 | +| HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 | |
| 115 | +| :------ | :--------- | :----------- | :--------- | :--------- | |
| 116 | +| 401 | unauthorized | Unable to authenticate (OAuth) | token 不合法，可能过期或 token 错误。 | 使用新的 token 访问。 | |
| 117 | +| 404 | organization_application_not_found | Could not find application for XXX/XXX from URI: XXX/XXX/users | App key 不存在。 | 检查 `orgName` 和 `appName` 是否正确或[创建应用](/product/enable_and_configure_IM.html#创建应用)。 | |
| 118 | + |
| 119 | +关于其他错误，你可以参考 [错误码](#错误码) 了解可能的原因。 |
| 120 | + |
| 121 | +### 获取指定离线消息的投递状态 |
| 122 | + |
| 123 | +获取用户的指定离线消息的投递状态，即查看该消息是否已投递。 |
| 124 | + |
| 125 | +#### HTTP 请求 |
| 126 | + |
| 127 | +```http |
| 128 | +GET https://{host}/{org_name}/{app_name}/users/{username}/offline_msg_status/{msg_id} |
| 129 | +``` |
| 130 | + |
| 131 | +##### 路径参数 |
| 132 | + |
| 133 | +| 参数 | 类型 | 是否必需 | 描述 | |
| 134 | +| :--------- | :----- | :------- | :---------------------------- | |
| 135 | +| `username` | String | 是 | 要获取离线消息状态的用户 ID。 | |
| 136 | +| `msg_id` | String | 是 | 要查看状态的离线消息 ID。 | |
| 137 | + |
| 138 | +其他参数及说明详见 [公共参数](#公共参数)。 |
| 139 | + |
| 140 | +##### 请求 header |
| 141 | + |
| 142 | +| 参数 | 类型 | 是否必需 | 描述 | |
| 143 | +| :-------------- | :----- | :------- | :-------------------- | |
| 144 | +| `Accept` | String | 是 | 内容类型。请填 `application/json`。 | |
| 145 | +| `Authorization` | String | 是 | App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。 | |
| 146 | + |
| 147 | +#### HTTP 响应 |
| 148 | + |
| 149 | +##### 响应 body |
| 150 | + |
| 151 | +如果返回的 HTTP 状态码为 `200`，表示请求成功，响应包体中的字段如下： |
| 152 | + |
| 153 | +| 字段 | 类型 | 描述 | |
| 154 | +| :----- | :--- | :--------------- | |
| 155 | +| `data` | JSON | 指定离线消息的投递状态。数据格式为 "消息 ID": "投递状态"。消息的投递状态有两种：<br/> - `delivered`：已投递；<br/> - `undelivered`：未投递。 | |
| 156 | + |
| 157 | +其他字段及说明详见 [公共参数](#公共参数)。 |
| 158 | + |
| 159 | +如果返回的 HTTP 状态码非 `200`，表示请求失败。你可以参考 [错误码](#错误码) 了解可能的原因。 |
| 160 | + |
| 161 | +#### 示例 |
| 162 | + |
| 163 | +##### 请求示例 |
| 164 | + |
| 165 | +```shell |
| 166 | +# 将 <YourAppToken> 替换为你在服务端生成的 App Token |
| 167 | + |
| 168 | +curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/users/user1/offline_msg_status/123' |
| 169 | +``` |
| 170 | + |
| 171 | +##### 响应示例 |
| 172 | + |
| 173 | +```json |
| 174 | +{ |
| 175 | + "action": "get", |
| 176 | + "uri": "https://XXXX/XXXX/XXXX/users/user1/offline_msg_status/123", |
| 177 | + "entities": [], |
| 178 | + "data": { |
| 179 | + "123": "delivered" |
| 180 | + }, |
| 181 | + "timestamp": 1542601830084, |
| 182 | + "duration": 5, |
| 183 | + "count": 0 |
| 184 | +} |
| 185 | +``` |
| 186 | + |
| 187 | +#### 错误码 |
| 188 | + |
| 189 | +如果返回的 HTTP 状态码非 `200`，表示请求失败，可能提示以下错误码： |
| 190 | + |
| 191 | +| HTTP 状态码 | 错误类型 | 错误提示 | 可能原因 | 处理建议 | |
| 192 | +| :---------- | :------------ | :-------------- | :------------------| :----------- | |
| 193 | +| 401 | unauthorized | Unable to authenticate (OAuth) | token 不合法，可能过期或 token 错误。 | 使用新的 token 访问。 | |
| 194 | +| 404 | organization_application_not_found | Could not find application for XXX/XXX from URI: XXX/XXX/users | App key 不存在。 | 检查 `orgName` 和 `appName` 是否正确或[创建应用](/product/enable_and_configure_IM.html#创建应用)。 | |
| 195 | + |
| 196 | +关于其他错误，你可以参考 [错误码](#错误码) 了解可能的原因。 |
0 commit comments