====== 用户体系集成 ====== 更新时间：2021-12-31 该文档已不再维护，请看新版 3.X 文档。 新版文档见：[[ccim:rest:accountsystem|用户体系集成]]。 ---- ===== 概述 ===== 介绍 AppKey 和环信 ID 的数据结构以及使用规则。 ==== Appkey 数据结构 ==== 当您申请了 AppKey 后，会得到一个 **xxxx#xxxx** 格式的字符串，字符串只能由小写字母数字组成，AppKey 是环信应用的唯一标识。前半部分 **org_name** 是在多租户体系下的唯一租户标识，后半部分 **app_name** 是租户下的 App 唯一标识（在环信后台创建一个 App 时填写的应用 ID 即是 app_name ）。下述的 REST API 中，**/{org_name}/{app_name}** 的请求，均是针对一个唯一的 AppKey 进行的。目前环信注册的 AppKey 暂不能由用户自己完成删除操作，如果对 APP 删除需要联系环信操作完成。 ^Appkey ^xxxx ^分隔符 ^xxxx ^描述^ |环信应用的唯一标识|org_name |#|app_name| app_name 只能是字母、数字、横线组合。长度不能超过 32 字符。| ==== 环信 ID 数据结构 ==== 环信作为一个聊天通道，只需要提供环信 ID （也就是 IM 用户名）和密码就够了。 ^名称 ^字段名 ^数据类型 ^描述^ |环信 ID |username |String |在 AppKey 的范围内唯一用户名，用户 ID 的长度在 64 字节以内。| |用户密码 |password |String |用户登录环信使用的密码。| ==== 环信 ID 使用规则 ==== 当 APP 和环信集成的时候，需要把 APP 系统内的已有用户和新注册的用户和环信集成，为每个已有用户创建一个环信的账号（环信 ID），并且 APP 有新用户注册的时候，需要同步的在环信中注册。 **在注册环信账户的时候，需要注意环信 ID 的规则：** * 使用英文字母和（或）数字的组合 * 不能使用中文 * 不能使用 email 地址 * 不能使用 UUID * 用户 ID 的长度在 64 字节以内 * 中间不能有空格或者井号（#）等特殊字符 * 允许的用户名正则 “[a-z0-9_-.]*”（a~z小写字母/数字/下划线/横线/英文句号），其他都不允许 **如果是大写字母会自动转成小写** * 不区分大小写。系统忽略大小写，认为 AA、Aa、aa、aA 都是一样的。如果系统已经存在了环信 ID 为 AA 的用户，再试图使用 aa 作为环信 ID 注册新用户，系统返回用户名重复，以此类推, 因此建议用户使用小写字母，否则可能遇到一些异常情况。但是请注意：环信 ID 在数据上的表现形式还是用户最初注册的形式，注册时候使用的大写就保存大写，是小写就保存小写。即：使用 AA 注册，环信保存的 ID 就是 AA；使用 Aa 注册，环信保存的 ID 就是 Aa，以此类推。 另：本文档中可能会交错使用“环信 ID”和“环信用户名”两个术语，但是请注意，这里两个的意思是一样的。 因为一个用户的环信 ID 和他的在 APP 中的用户名并不需要一致，只需要有一个明确的对应关系。例如，用户名是 example@easemob.com，当这个用户登录到 APP 的时候，可以登录成功之后，再登录环信的服务器，所以这时候，只需要能够从 example@easemob.com 推导出这个用户的环信 ID 即可。 **注意：**以下所有 API 均需要 org 管理员或 APP 管理员权限才能访问。 强烈建议保护好 org 管理员，APP 管理员的用户名和密码以及 APP 的 client_id 和 client_secret，尽量只在 APP 的服务器后台对环信用户做增删改查的管理，包括新用户注册。为了您的信息安全，请一定不要将 org 管理员或 APP 管理员的用户名和密码写死在手机客户端中，因为手机 APP 很容易被反编译，从而导致别人获取到您的管理员账号和密码，导致数据泄露。 ---- ====== REST API ====== 介绍关于 IM 用户体系集成过程中，需要使用到的 REST API 文档详细说明，可以通过使用文档中嵌入的[[http://api-docs.easemob.com/|Easemob REST API]]进行在线测试。 ===== 请求域名 ===== 环信不同数据中心的REST API请求域名： |数据中心|REST API请求地址|WebSocket访问域名| |国内1区|a1.easemob.com 或 a1.easecdn.com|im-api-v2.easemob.com 或 im-api-v2.easecdn.com| |国内2区|a31.easemob.com 或 a31.easecdn.com|im-api-v2-31.easemob.com 或 im-api-v2-31.easecdn.com| |国内VIP区|请咨询商务经理|请咨询商务经理| |客服专用|请咨询商务经理|请咨询商务经理| |新加坡1区|a1-sgp.easemob.com 或 a1-sgp.easecdn.com|im-api-sgp-v2.easemob.com 或 im-api-sgp-v2.easecdn.com| |美东1区|a41.easemob.com 或 a41.easecdn.com|msync-api-41.easemob.com 或 msync-api-41.easecdn.com| |法兰克福1区|a51.easemob.com 或 a51.easecdn.com|msync-api-51.easemob.com 或 msync-api-51.easecdn.com| 应用所在数据中心可以在环信用户管理后台>应用列表找到对应的appkey点击"查看">即时通讯>服务概览中查看： {{im:000quickstart:console-查看restapi访问地址.jpg?800|}} **注意：** 1.为满足不同客户的业务需求，环信在多地部署了数据中心。不同数据中心的 REST API 请求域名不同。请根据您所在数据中心选择请求域名。 2.国内 VIP 区、客服专区客户请联系商务经理索要 REST API 请求地址。 3.支持 HTTP 和 HTTPS。 ===== 获取管理员权限token ===== 环信提供的 REST API 需要权限才能访问，权限通过发送 HTTP 请求时携带 token 来体现，下面描述获取 token 的方式。说明：API 描述的时候使用到的 {APP 的 client_id} 之类的这种参数需要替换成具体的值。 **重要提醒： ** 获取 token 时服务器会返回 token 有效期，具体值参考接口返回的 expires_in 字段值。由于网络延迟等原因，系统不保证 token 在此值表示的有效期内绝对有效，如果发现 token 使用异常请重新获取新的 token，比如“http response code”返回 401。另外，请不要频繁向服务器发送获取 token 的请求，同一账号发送此请求超过一定频率会被服务器封号，切记，切记！！ client_id 和 client_secret 可以在环信管理后台的 [[http://www.google.com|APP 详情页面]]看到。 === HTTP Request === ^{{:im:server:ready:post.png?nolink&90 |}}^/**{org_name}/{app_name}/token**^ === Request Headers === ^参数^说明^ |Content-Type|application/json| === Request Body === ^参数^说明^ |grant_type|client_credentials| |client_id|App的client_id，可在[[https://console.easemob.com/app-detail/detail|app详情页找到]]| |client_secret|App的client_secret，可在[[https://console.easemob.com/app-detail/detail|app详情页找到]]| |client_secret|App的client_secret，可在[[https://console.easemob.com/app-detail/detail|app详情页找到]]| |''%%ttl%%'' |String | 必需 |token 有效期，单位为秒(s)。此外，也可通过环信即时通讯云控制台设置，参见 [[https://console.easemob.com/app/applicationOverview/userManagement|用户认证详情页面]]。该参数值以最新设置为准。| === Response Body === ^参数^说明^ |access_token |有效的token字符串| |expires_in |token 有效期，单位为秒(s)。| |application |当前 App 的 UUID 值| === 请求示例 === curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{ "grant_type": "client_credentials", "client_id": "YXA6i-Ak8Ol4Eei2l11ZjV-EAg", "client_secret": "YXA6VunqiNxoB7IwXHInk1cGiXOOJfc", "ttl": "1024000" }' 'http://a1.easemob.com/easemob-demo/testapp/token' === 可能返回的结果示例 === **返回值200，表示成功返回token** { "access_token": "YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw", "expires_in": 5184000, "application": "8be024f0-e978-11e8-b697-5d598d5f8402" } **返回值400，表示 client_id 或 client_secret 错误** { "access_token": "YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw", "expires_in": 1024000, "application": "8be024f0-e978-11e8-b697-5d598d5f8402" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ===== 用户管理 ===== 环信提供多个接口实现对 IM 用户的注册、获取、修改、删除等管理功能。 ^名称^请求^描述^ |注册单个用户|/{org_name}/{app_name}/users|注册一个 IM 用户，有**开放注册**和**授权注册**两种模式| |批量注册用户|/{org_name}/{app_name}/users|注册多个 IM 用户，仅支持授权注册| |获取单个用户|/{org_name}/{app_name}/users/{username}|获取单个 IM 用户| |批量获取用户|/{org_name}/{app_name}/users|获取应用下的多个 IM 用户| |删除单个用户|/{org_name}/{app_name}/users/{username}|删除单个 IM 用户| |批量删除用户|/{org_name}/{app_name}/users|批量删除多个 IM 用户| |修改用户密码|/{org_name}/{app_name}/users/{username}/password|修改 IM 用户的密码| |设置推送消息显示昵称|/{org_name}/{app_name}/users/{username}|设置 IM 用户推送消息显示的昵称| |设置推送消息展示方式|/{org_name}/{app_name}/users/{username}|设置 IM 用户推送消息展示为仅通知还是详情可见| |设置免打扰|/{org_name}/{app_name}/users/{username}|设置 IM 用户是否开启免打扰模式，以及开启/关闭免打扰的时间| 在 URL 指定的 org 和 APP 中创建一个新的用户，分两种模式：**开放注册**和**授权注册**。 * “开放注册”模式：注册环信账号时，不用携带管理员身份认证信息； * “授权注册”模式：注册环信账号时，必须携带管理员身份认证信息。推荐使用“授权注册”，这样可以防止某些已经获取了注册 URL 和知晓注册流程的人恶意向服务器大量注册垃圾用户。 **注意：** * 以下 API 中提到的 ${token} 是个变量，使用时需要替换成通过 APP 的 client_id 和 client_secret 获取到的 token。 * 在注册环信 id 时，建议不要使用有序的 id 进行注册，防止其他人知道注册 id 的顺序，恶意发送大量的垃圾消息。 * 服务器端给自己用户注册账号的同时，在调用环信的rest接口给用户在注册一个环信id与自己的用户绑定，并返回给客户端，客户端拿到自己服务器用户的账号密码登录后，在拿环信id密码在登录环信服务器。 ==== 注册单个用户(开放) ==== 用户可以在登录客户端 SDK 后自行通过账号密码注册账号的接口。 === HTTP Request === ^{{:im:server:ready:post.png?nolink&90 |}}^**/{org_name}/{app_name}/users**^ === Request Headers === ^参数^说明^ |Content-Type|application/json| === Request Body === ^参数^说明^ |username|环信 ID ;也就是 IM 用户名的唯一登录账号，长度不可超过64个字符长度| |password|登录密码，长度不可超过64个字符长度| |nickname|iOS推送昵称（可选），在 iOS Apns 推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，长度不可超过100个字符，如果需要环信存储用户昵称，头像等个人信息的，请参考[[https://docs-im.easemob.com/im/server/ready/usermetadata#%E8%AE%BE%E7%BD%AE%E7%94%A8%E6%88%B7%E5%B1%9E%E6%80%A7|用户属性]]| === Response Body === 在返回值中查看entities字段包含的信息 ^参数^说明^ |uuid|用户的UUID，标识字段| |type|"user"用户类型| |username|用户名，也就是环信 ID | |nickname|iOS推送昵称（可选），在 iOS Apns 推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，长度不可超过100个字符| |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| === 请求示例 === curl -X POST -i "https://a1.easemob.com/easemob-demo/testapp/users" -d '{"username":"user1","password":"123","nickname":"testuser"}' === 可能返回的结果示例 === **返回值200，表示创建 IM 用户成功** { "action": "post", "application": "8be024f0-e978-11e8-b697-5d598d5f8402", "path": "/users", "uri": "https://a1.easemob.com/easemob-demo/testapp/users", "entities": [ { "uuid": "0ffe2d80-ed76-11e8-8d66-279e3e1c214b", "type": "user", "created": 1542795196504, "modified": 1542795196504, "username": "user1", "activated": true, "nickname": "testuser" } ], "timestamp": 1542795196515, "duration": 0, "organization": "easemob-demo", "applicationName": "testapp" } **返回值400，表示用户已存在、用户名或密码为空、用户名不合法** { "error": "duplicate_unique_property_exists", "timestamp": 1542795141631, "duration": 0, "exception": "org.apache.usergrid.persistence.exceptions.DuplicateUniquePropertyExistsException", "error_description": "Application null Entity user requires that property named username be unique, value of User1 exists" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 注册单个用户(授权) ==== 服务端需要校验有效的token权限才能进行操作，授权注册的接口。 === HTTP Request === ^{{:im:server:ready:post.png?nolink&90 |}}^**/{org_name}/{app_name}/users**^ === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Request Body === ^参数^说明^ |username|环信 ID ;也就是 IM 用户的唯一登录账号，长度不可超过64个字符长度| |password|登录密码，长度不可超过64个字符长度| |nickname|iOS推送昵称（可选），在 iOS Apns 推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，长度不可超过100个字符，如果需要环信存储用户昵称，头像等个人信息的，请参考[[https://docs-im.easemob.com/im/server/ready/usermetadata#%E8%AE%BE%E7%BD%AE%E7%94%A8%E6%88%B7%E5%B1%9E%E6%80%A7|用户属性]]| === Response Body === 在返回值中查看entities字段包含的信息 ^参数^说明^ |uuid|用户的UUID，标识字段| |type|"user"用户类型| |username|用户名，也就是环信 ID | |nickname|昵称（可选），在 iOS Apns 推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，环信是不保存用户昵称，头像等个人信息的，需要自己服务器保存并与给自己用户注册的IM用户名绑定| |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| === 请求示例 === curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer WMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw12' -d '[ { "username": "user1", "password": "123", "nickname": "testuser" } ]' 'http://a1.easemob.com/easemob-demo/testapp/users' === 可能返回的结果示例 === **返回值200，表示创建 IM 用户成功** { "action": "post", "application": "a2e433a0-ab1a-11e2-a134-85fca932f094", "params": {}, "path": "/users", "uri": "https://a1.easemob.com/easemob-demo/testapp/users", "entities": [{ "uuid": "7f90f7ca-bb24-11e2-b2d0-6d8e359945e4", "type": "user", "created": 1368377620796, "modified": 1368377620796, "username": "user1", "activated": true "nickname": "testuser" }], "timestamp": 1368377620793, "duration": 125, "organization": "easemob-demo", "applicationName": "testapp" } **返回值400，表示用户已存在、用户名或密码为空、用户名不合法** { "error": "duplicate_unique_property_exists", "timestamp": 1537871738097, "duration": 0, "exception": "org.apache.usergrid.persistence.exceptions.DuplicateUniquePropertyExistsException", "error_description": "Application null Entity user requires that property named username be unique, value of ccccc1 exists" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "auth_bad_access_token", "timestamp": 1543479294349, "duration": 0, "exception": "org.apache.usergrid.rest.exceptions.SecurityException", "error_description": "Unable to authenticate due to corrupt access token" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 批量注册用户 ==== 批量注册是授权注册方式，服务端需要校验有效的token权限才能进行操作。每次调用接口时，注册用户数量有最大限制，详见[[im:server:help:restastrict|接口限流说明]]。 === HTTP Request === ^{{:im:server:ready:post.png?nolink&90 |}}^**/{org_name}/{app_name}/users**^ === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Request Body === ^参数^说明^ |username|环信 ID ;也就是 IM 用户的唯一登录账号，长度不可超过64个字符| |password|登录密码，长度不可超过64个字符| |nickname|iOS推送昵称（可选），在 iOS Apns 推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，长度不可超过100个字符，如果需要环信存储用户昵称，头像等个人信息的，请参考[[https://docs-im.easemob.com/im/server/ready/usermetadata#%E8%AE%BE%E7%BD%AE%E7%94%A8%E6%88%B7%E5%B1%9E%E6%80%A7|用户属性]]| === Response Body === 在返回值中查看entities字段包含的信息 ^参数^说明^ |uuid|用户的UUID，标识字段| |type|"user"用户类型| |username|用户名，也就是环信 ID | |nickname|昵称（可选），在 iOS Apns 推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，环信是不保存用户昵称，头像等个人信息的，需要自己服务器保存并与给自己用户注册的IM用户名绑定| |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| === 请求示例1 === curl -X POST -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE" -i "https://a1.easemob.com/easemob-demo/testapp/users" -d '[{"username":"user1", "password":"123","nickname":"testuser1"}, {"username":"user2", "password":"456","nickname":"testuser2"}]' === 可能返回的结果示例 === **返回值200，表示成功返回token** { "action": "post", "application": "22bcffa0-8f86-11e6-9df8-516f6df68c6d", "path": "/users", "uri": "https://a1.easemob.com/easemob-demo/testapp/users", "entities": [ { "uuid": "278b5e60-e27b-11e8-8f9b-d5d83ebec806", "type": "user", "created": 1541587920710, "modified": 1541587920710, "username": "user1", "activated": true, "nickname": "testuser1" }, { "uuid": "278bac80-e27b-11e8-b192-73e4cd5078a5", "type": "user", "created": 1541587920712, "modified": 1541587920712, "username": "user2", "activated": true, "nickname": "testuser2" } ], "timestamp": 1541587920714, "data": [], "duration": 0, "organization": "1122161011178276", "applicationName": "testapp" } === 请求示例2 === curl -X POST -H "Authorization: Bearer YWMtP_8IisA-EeK-a5cNq4Jt3QAAAT7fI10IbPuKdRxUTjA9CNiZMnQIgk0LEUE" -i "https://a1.easemob.com/easemob-demo/testapp/users" -d '[{"username":"user1", "password":"123","nickname":"testuser1"}, {"username":"user2", "password":"456","nickname":"testuser2"}, {"username":"user3", "password":"789","nickname":"testuser3"}]' 当请求 body 中存在已经注册过的 user3 时，那么请求会成功并且user1、user2也会注册成功，response 中的 data 数组内是返回存在问题的用户。 === 可能返回的结果示例 === **返回值200，表示成功返回token** { "action": "post", "application": "22bcffa0-8f86-11e6-9df8-516f6df68c6d", "path": "/users", "uri": "https://a1.easemob.com/easemob-demo/testapp/users", "entities": [ { "uuid": "278b5e60-e27b-11e8-8f9b-d5d83ebec806", "type": "user", "created": 1541587920710, "modified": 1541587920710, "username": "user1", "activated": true, "nickname": "testuser1" }, { "uuid": "278bac80-e27b-11e8-b192-73e4cd5078a5", "type": "user", "created": 1541587920712, "modified": 1541587920712, "username": "user2", "activated": true, "nickname": "testuser2" } ], "timestamp": 1541587920714, "data": [ { "username": "user3", "registerUserFailReason": "the user3 already exists" } ], "duration": 0, "organization": "1122161011178276", "applicationName": "testapp" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ===== 获取用户token ===== 环信提供2种方式进行登录：1.使用“用户名”和“密码”进行登录；2.使用”用户名“+”用户Token"进行登录 方式1:在SDK进行登录时，使用“用户名”和“密码”进行登录。 该方式集成相对简单，用户注册后，直接使用“用户名”和“密码”进行登录。登录成功后，SDK会获取一个长期的用户token。 方式2:开发者使用RESTful API在自己的应用服务器管理用户token，在端上登录时，由应用服务器下发用户token，SDK使用用户名和用户token进行登录。 该方式开发者可以对用户token进行管理。获取用户token时，可以设置token有效期。 === HTTP Request === ^{{:im:server:ready:post.png?nolink&90 |}}^/**{org_name}/{app_name}/token**^ === Request Headers === ^参数^说明^ |Content-Type|application/json| === Request Body === ^参数^说明^ |grant_type|password| |username|用户名| |password|密码| |ttl|token 有效期，单位为秒(s)。此外，也可通过环信即时通讯云控制台设置，参见 [[https://console.easemob.com/app/applicationOverview/userManagement|用户认证详情页面]]。该参数值以最新设置为准。| === Response Body === ^参数^说明^ |access_token |有效的用户token字符串| |expires_in |token 有效时间，以秒为单位，在有效期内不需要重复获取| |user |UUID：用户的UUID、type：用户类型、created：创建时间、modified：修改时间、username：用户名、activated：是否激活| === 请求示例 === curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{ "grant_type": "password", "username": "C", "password": "1" "ttl": "1024000" }' 'http://a1.easemob.com/easemob-demo/testapp/token' === 可能返回的结果示例 === **返回值200，表示成功返回token** { "access_token": "YWMtrR6ECkz8Eeyx6Y9j1eX9kbsMrFep3U6BvVj7KSnNonWqRx7gTPwR7Kzl-Q_xISNOAwMAAAF9UPZqbQAPoAAtYK9fWgaTNyuWoB3-6nGf_TXBx3Nt3XRZST-elU0x2A", "expires_in": 1024000, "user": { "uuid": "aa471ee0-4cfc-11ec-ace5-f90ff121234e", "type": "user", "created": 1637740861395, "modified": 1637740861395, "username": "c", "activated": true } } **返回值400，表示 username 或 password 错误** { "error": "invalid_grant", "timestamp": 1637741269908, "duration": 0, "error_description": "invalid password" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 获取单个用户 ==== 获取单个 IM 用户的详细信息接口。 === HTTP Request === ^{{:im:server:ready:get.png?nolink&90 |}}^**/{org_name}/{app_name}/users/{username}**^ 需要在请求时对应填写{username}，需要获取的 IM 用户名。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Response Body === 在返回值中查看entities字段包含的信息 ^参数^说明^ |uuid|用户的UUID，标识字段| |type|"user"用户类型| |username|用户名，也就是环信 ID | |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| |nickname|昵称（可选），在 iOS Apns 推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，环信是不保存用户昵称，头像等个人信息的，需要自己服务器保存并与给自己用户注册的IM用户名绑定| |notification_display_style|消息提醒方式，“0”仅通知，“1“通知以及消息详情，没有设置返不会返回| |notification_no_disturbing|免打扰的设置。"false"代表免打扰关闭，“true”免打扰开启，没有设置返不会返回| |notification_no_disturbing_start|免打扰的开始时间。数字代表开始时间，例如“8”代表每日8:00开启免打扰，没有设置则不会返回| |notification_no_disturbing_end|免打扰的结束时间。数字代表结束时间，例如“18”代表每日18:00关闭免打扰，没有设置则不会返回| |notification_ignore_63112447328257|屏蔽/取消屏蔽群组消息的离线推送的设置。数字代表群组id，“true”已屏蔽，“false“未屏蔽，没有设置则不会返回| |notifier_name|客户端推送证书名称，没有设置则不会返回| |device_token|推送token，没有则不会返回| === 请求示例 === curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1' === 可能返回的结果示例 === **返回值200，表示获取用户信息成功** { "action": "get", "path": "/users", "uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1", "entities": [ { "uuid": "0ffe2d80-ed76-11e8-8d66-279e3e1c214b", "type": "user", "created": 1542795196504, "modified": 1542795196504, "username": "user1", "activated": true, "nickname": "testuser" } ], "timestamp": 1542798985011, "duration": 6, "count": 1 } **返回值404，表示该用户不存在** { "error": "service_resource_not_found", "timestamp": 1542799099701, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } **返回值401，未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542799184277, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/b2aade90-e978-11e8-a974-f3368f82e4f1]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 批量获取用户 ==== 该接口默认返回按照创建时间排序，如果需要指定获取数量，需加上参数 limit=N，N 为数量值。关于分页：如果 DB 中的数量大于 N，返回 JSON 会携带一个字段“cursor”,我们把它叫做”游标”，该游标可理解为结果集的指针，值是变化的。往下取数据的时候带着游标，就可以获取到下一页的值。如果还有下一页，返回值里依然还有这个字段，直到没有这个字段，说明已经到最后一页。cursor的意义在于数据（真）分页。 === HTTP Request === ^{{:im:server:ready:get.png?nolink&90 |}}^**/{org_name}/{app_name}/users**^ 需要在请求时对应填写{username}，需要获取的 IM 用户名。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Response Body === 在返回值中查看entities字段包含的信息 ^参数^说明^ |uuid|用户的UUID，标识字段| |type|"user"用户类型| |username|用户名，也就是环信 ID | |nickname|昵称（可选），在 iOS Apns 推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，环信是不保存用户昵称，头像等个人信息的，需要自己服务器保存并与给自己用户注册的IM用户名绑定| |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| |notification_display_style|消息提醒方式，“true”仅通知，“false“通知以及消息详情，没有设置则不会返回| |notification_no_disturbing|免打扰的设置。"0"代表免打扰关闭，“1”免打扰开启，没有设置则不会返回| |notification_no_disturbing_start|免打扰的开始时间。数字代表开始时间，例如“8”代表每日8:00开启免打扰，没有设置则不会返回| |notification_no_disturbing_end|免打扰的结束时间。数字代表结束时间，例如“18”代表每日18:00关闭免打扰，没有设置则不会返回| |notification_ignore_63112447328257|屏蔽/取消屏蔽群组消息的离线推送的设置。数字代表群组id，“true”已屏蔽，“false“未屏蔽，没有设置则不会返回| |notifier_name|客户端推送证书名称，没有设置则不会返回| |device_token|推送token，没有则不会返回| 不分页 === 请求示例 === curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users?limit=2' 使用返回的cursor获取下一页 curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users?limit=2&cursor=LTgzNDAxMjM3OToxTEFnNE9sNEVlaVQ0UEdhdmJNR2tB' === 可能返回的结果示例 === **返回值200，表示获取用户信息成功** { "action": "get", "params": { "limit": [ "2" ] }, "path": "/users", "uri": "http://a1.easemob.com/easemob-demo/testapp/users", "entities": [ { "uuid": "ab90eff0-e978-11e8-9174-8f161649a182", "type": "user", "created": 1542356511855, "modified": 1542356511855, "username": "user1", "activated": true, "nickname": "user1" }, { "uuid": "b2aade90-e978-11e8-a974-f3368f82e4f1", "type": "user", "created": 1542356523769, "modified": 1542356523769, "username": "user2", "activated": true, "nickname": "user2" } ], "timestamp": 1542558467056, "duration": 11, "cursor": "LTgzNDAxMjM3OToxTEFnNE9sNEVlaVQ0UEdhdmJNR2tB", "count": 2 } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542559172189, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] > 分页 === 请求示例 === curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users?limit=2&cursor=LTgzNDAxMjM3OToxTEFnNE9sNEVlaVQ0UEdhdmJNR2tB' === 可能返回的结果示例 === **返回值200，表示获取用户信息成功** { "action": "get", "params": { "cursor": [ "LTgzNDAxMjM3OToxTEFnNE9sNEVlaVQ0UEdhdmJNR2tB" ], "limit": [ "2" ] }, "path": "/users", "uri": "http://a1.easemob.com/easemob-demo/testapp/users", "entities": [ { "uuid": "fef7f250-e983-11e8-ba39-0fed7dcc3cdd", "type": "user", "created": 1542361376245, "modified": 1542361376245, "username": "testuser", "activated": true, "nickname": "testuser" } ], "timestamp": 1542559337702, "duration": 2, "count": 1 } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542559373319, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 删除单个用户 ==== 删除一个用户，如果此用户是群组或者聊天室的群主owner，系统会同时删除这些群组和聊天室。请在操作时进行确认。 === HTTP Request === ^{{:im:server:ready:delete.png?nolink&90|}}^**/{org_name}/{app_name}/users/{username}**^ 需要在请求时对应填写{username}，需要删除的 IM 用户名。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === 请求示例 === curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users/user1' === 可能返回的结果示例 === **返回值200，表示用户删除成功** { "action": "delete", "application": "8be024f0-e978-11e8-b697-5d598d5f8402", "path": "/users", "uri": "https://a1.easemob.com/easemob-demo/testapp/users", "entities": [ { "uuid": "ab90eff0-e978-11e8-9174-8f161649a182", "type": "user", "created": 1542356511855, "modified": 1542356511855, "username": "user1", "activated": true, "nickname": "user1" } ], "timestamp": 1542559539776, "duration": 39, "organization": "easemob-demo", "applicationName": "testapp" } **返回值404，表示该用户不存在** { "error": "service_resource_not_found", "timestamp": 1542559595134, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "service_resource_not_found", "timestamp": 1542559595134, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 批量删除用户 ==== 删除某个 APP 下指定数量的环信账号。可一次删除 N 个用户，数值可以修改。建议这个数值在100-500之间，不要过大。需要注意的是，这里只是批量的一次性删除掉 N个用户，具体删除哪些并没有指定，可以在返回值中查看到哪些用户被删除掉了。 === HTTP Request === ^{{:im:server:ready:delete.png?nolink&90|}}^**/{org_name}/{app_name}/users**^ === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === 请求示例 === curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users?limit=2' === 可能返回的结果示例 === **返回值200，表示用户删除成功** { "action": "delete", "application": "8be024f0-e978-11e8-b697-5d598d5f8402", "params": { "limit": [ "2" ] }, "path": "/users", "uri": "https://a1.easemob.com/easemob-demo/testapp/users", "entities": [ { "uuid": "b2aade90-e978-11e8-a974-f3368f82e4f1", "type": "user", "created": 1542356523769, "modified": 1542597334500, "username": "user2", "activated": true, "nickname": "testuser" }, { "uuid": "b98ad170-e978-11e8-8fce-7f76daa76557", "type": "user", "created": 1542356535303, "modified": 1542356535303, "username": "user3", "activated": true, "nickname": "user3" } ], "timestamp": 1542867197779, "duration": 504, "organization": "easemob-demo", "applicationName": "testapp", "cursor": "LTgzNDAxMjM3OTpfdmZ5VU9tREVlaTZPUV90ZmN3ODNR" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542867266449, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:delete:8be024f0-e978-11e8-b697-5d598d5f8402:/users]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 修改用户密码 ==== 可以通过服务端接口修改 IM 用户的登录密码，不需要提供原密码。 === HTTP Request === ^{{:im:server:ready:put.png?nolink&90|}}^**/{org_name}/{app_name}/users/{username}/password**^ 需要在请求时对应填写{username}，需要修改密码的 IM 用户名。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Request Body === ^参数^说明^ |newpassword|${新密码指定的字符串}| === 请求示例 === curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -d '{ "newpassword": "123" }' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/password' === 可能返回的结果示例 === **返回值200，表示用户密码修改成功** { "action": "set user password", "timestamp": 1542595598924, "duration": 8 } **返回值404，表示该用户不存在** { "error": "entity_not_found", "timestamp": 1542595648340, "duration": 0, "exception": "org.apache.usergrid.persistence.exceptions.EntityNotFoundException", "error_description": "User null not found" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 设置推送昵称 ==== 设置用户的推送昵称，在离线推送时使用。 === HTTP Request === ^{{:im:server:ready:put.png?nolink&90|}}^** /{org_name}/{app_name}/users/{username}**^ 需要在请求时对应填写{username}，需要修改推送昵称的 IM 用户名。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Request Body === ^参数^说明^ |nickname|将要改成的推送昵称信息| === Response Body === 在返回值中查看entities字段包含的信息 ^参数^说明^ |uuid|用户的UUID，标识字段| |type|"user"用户类型| |username|用户名，也就是环信 ID | |nickname|昵称（可选），在离线推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，环信是不保存用户昵称，头像等个人信息的，需要自己服务器保存并与给自己用户注册的IM用户名绑定| |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| === 请求示例 === curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -d '{ "nickname": "testuser" }' 'http://a1.easemob.com/easemob-demo/testapp/users/user1' === 可能返回的结果示例 === **返回值200，表示用户推送昵称修改成功** { "action": "put", "application": "8be024f0-e978-11e8-b697-5d598d5f8402", "path": "/users", "uri": "https://a1.easemob.com/easemob-demo/testapp/users", "entities": [ { "uuid": "4759aa70-eba5-11e8-925f-6fa0510823ba", "type": "user", "created": 1542595573399, "modified": 1542596083687, "username": "user1", "activated": true, "nickname": "testuser" } ], "timestamp": 1542596083685, "duration": 6, "organization": "easemob-demo", "applicationName": "testapp" } **返回值400，表示该用户不存在** { "error": "required_property_not_found", "timestamp": 1542597341919, "duration": 0, "exception": "org.apache.usergrid.persistence.exceptions.RequiredPropertyNotFoundException", "error_description": "Entity user requires a property named username" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542597533232, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:put:8be024f0-e978-11e8-b697-5d598d5f8402:/users]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 设置推送消息展示方式 ==== 设置推送消息至客户端的方式，修改后及时有效。服务端对应不同的设置，向用户发送不同展示方式的消息。 === HTTP Request === ^{{:im:server:ready:put.png?nolink&90|}}^**/{org_name}/{app_name}/users/{username}**^ 需要在请求时对应填写{username}，需要推送的 IM 用户名。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Request Body === ^参数^说明^ |notification_display_style|“0”仅通知，“1“通知以及消息详情| === Response Body === 在返回值中查看entities字段包含的信息 ^参数^说明^ |uuid|用户的UUID，标识字段| |type|"user"用户类型| |username|用户名，也就是环信 ID | |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| |notification_display_style|消息提醒方式，“0”仅通知，“1“通知以及消息详情| === 请求示例 === curl -X PUT -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EKeAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFDSEF2E" -i https://a1.easemob.com/easemob-demo/testapp/users/a -d '{"notification_display_style": "1"}' === 可能返回的结果示例 === **返回值200，表示修改成功** { "action" : "put", "application" : "17d59e50-0aee-11e8-8092-0dc80c0f5e99", "path" : "/users", "uri" : "https://a1.easemob.com/easemob-demo/testapp/users", "entities" : [ { "uuid" : "3b8c9890-7b9a-11e8-9d88-f50bf55cafad", "type" : "user", "created" : 1530276298905, "modified" : 1534407146060, "username" : "user1", "activated" : true, "notification_no_disturbing" : false, "notification_no_disturbing_start" : 1, "notification_no_disturbing_end" : 3, "notification_display_style" : 1, "nickname" : "testuser", "notifier_name" : "2882303761517426801" } ], "timestamp" : 1534407146058, "duration" : 3, "organization" : "1112171214115068", "applicationName" : "testapp" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 设置免打扰 ==== 设置 IM 用户免打扰，在免打扰期间，用户将不会收到离线消息推送。 === HTTP Request === ^{{:im:server:ready:put.png?nolink&90|}}^**/{org_name}/{app_name}/users/{username}**^ 需要在请求时对应填写{username}，需要设置免打扰的 IM 用户名 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Request Body === ^参数^说明^ |notification_no_disturbing|是否免打扰，false 代表免打扰关闭，true 免打扰开启| |notification_no_disturbing_start|免打扰起始时间，单位是小时| |notification_no_disturbing_end|免打扰结束时间，单位是小时| === Response Body === 在返回值中查看entities字段包含的信息 ^参数^说明^ |uuid|用户的UUID，标识字段| |type|"user"用户类型| |username|用户名，也就是环信 ID | |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| |notification_display_style|免打扰的设置。"0"代表免打扰关闭，“1”免打扰开启| |notification_no_disturbing_start|免打扰的开始时间。数字代表开始时间，例如“8”代表每日8:00开启免打扰| |notification_no_disturbing_end|免打扰的结束时间。数字代表结束时间，例如“18”代表每日18:00关闭免打扰| === 请求示例 === **设置免打扰时间** curl -X PUT -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EKeAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFDSEF2E" -i "https://a1.easemob.com/easemob-demo/testapp/users/a " -d '{"notification_no_disturbing": true,"notification_no_disturbing_start": "1","notification_no_disturbing_end": "3"}' **取消免打扰** curl -X PUT -H "Authorization: Bearer YWMtSozP9jHNEeSQegV9EKeAQAAAUlmBR2bTGr-GP2xNh8GhUCdKViBFDSEF2E" -i "https://a1.easemob.com/easemob-demo/testapp/users/a " -d '{"notification_no_disturbing": false}' === 可能返回的结果示例 === **返回值200，表示设置成功** { "action" : "put", "application" : "17d59e50-0aee-11e8-8092-0dc80c0f5e99", "path" : "/users", "uri" : "https://a1.easemob.com/easemob-demo/testapp/users", "entities" : [ { "uuid" : "3b8c9890-7b9a-11e8-9d88-f50bf55cafad", "type" : "user", "created" : 1530276298905, "modified" : 1534405429835, "username" : "User1", "activated" : true, "notification_no_disturbing" : true, "notification_no_disturbing_start" : 1, "notification_no_disturbing_end" : 3, "notification_display_style" : 0, "nickname" : "testuser", "notifier_name" : "2882303761517426801" } ], "timestamp" : 1534405429833, "duration" : 4, "organization" : "1112171214115068", "applicationName" : "testapp" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ===== 好友与黑名单 ===== 环信提供多个接口实现对 IM 用户的好友以及黑名单进行添加和移除。 ^名称^请求^描述^ |添加好友|/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}|添加为好友| |移除好友|/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}|移除好友列表中的用户| |获取好友列表|/{org_name}/{app_name}/users/{owner_username}/contacts/users|获取好友列表以及信息| |获取黑名单|/{org_name}/{app_name}/users/{owner_username}/blocks/users|获取黑名单以及信息| |添加黑名单|/{org_name}/{app_name}/users/{owner_username}/blocks/users|拉黑用户，添加至黑名单| |移除黑名单|/{org_name}/{app_name}/users/{owner_username}/blocks/users/{blocked_username}|除黑名单中的用户| ==== 添加好友 ==== 添加好友，好友必须是和自己在一个 APPkey 下的 IM 用户，单用户ID可以添加的好友数量，请参考不同版本[[http://www.easemob.com/pricing/im|数量]] === HTTP Request === ^{{:im:server:ready:post.png?nolink&90|}}^**/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}**^ 需要在请求时对应填写{owner_username}，要添加好友的用户名，以及{friend_username}，好友用户名。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === 请求示例 === curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/contacts/users/user2' === 可能返回的结果示例 === **返回值200，表示添加好友成功** { "action": "post", "application": "8be024f0-e978-11e8-b697-5d598d5f8402", "path": "/users/4759aa70-eba5-11e8-925f-6fa0510823ba/contacts", "uri": "https://a1.easemob.com/easemob-demo/testapp/users/4759aa70-eba5-11e8-925f-6fa0510823ba/contacts", "entities": [ { "uuid": "b2aade90-e978-11e8-a974-f3368f82e4f1", "type": "user", "created": 1542356523769, "modified": 1542597334500, "username": "user2", "activated": true, "nickname": "testuser" } ], "timestamp": 1542598913819, "duration": 63, "organization": "easemob-demo", "applicationName": "testapp" } **返回值404，表示此IM用户或被添加的好友不存在** { "error": "service_resource_not_found", "timestamp": 1542598965722, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } **返回值401，未授权[无token、token错误、token过期]** { "error": "auth_bad_access_token", "timestamp": 1542599042628, "duration": 0, "exception": "org.apache.usergrid.rest.exceptions.SecurityException", "error_description": "Unable to authenticate due to corrupt access token" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 移除好友 ==== 从 IM 用户的好友列表中移除一个 IM 用户。 === HTTP Request === ^{{:im:server:ready:delete.png?nolink&90|}}^**/{org_name}/{app_name}/users/{owner_username}/contacts/users/{friend_username}**^ 需要在请求时对应填写{owner_username}，要删除好友的用户名，以及{friend_username}，被删除好友的用户名。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === 请求示例 === curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/contacts/users/user2' === 可能返回的结果示例 === **返回值200，表示好友删除成功** { "action": "delete", "application": "8be024f0-e978-11e8-b697-5d598d5f8402", "path": "/users/4759aa70-eba5-11e8-925f-6fa0510823ba/contacts", "uri": "https://a1.easemob.com/easemob-demo/testapp/users/4759aa70-eba5-11e8-925f-6fa0510823ba/contacts", "entities": [ { "uuid": "b2aade90-e978-11e8-a974-f3368f82e4f1", "type": "user", "created": 1542356523769, "modified": 1542597334500, "username": "user2", "activated": true, "nickname": "testuser" } ], "timestamp": 1542599266616, "duration": 350, "organization": "easemob-demo", "applicationName": "testapp" } **返回值404，表示此IM用户或被删除的好友不存在** { "error": "service_resource_not_found", "timestamp": 1542599413796, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542599447198, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:delete:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 获取好友列表 ==== 获取 IM 用户的好友列表。 === HTTP Request === ^{{:im:server:ready:get.png?nolink&90|}}^**/{org_name}/{app_name}/users/{owner_username}/contacts/users**^ 需要在请求时对应填写{owner_username}，获取好友列表的用户名 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Response Body === ^参数^说明^ |username|“user1”, “user2”，获取到的好友列表| === 请求示例 === curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/contacts/users' === 可能返回的结果示例 === **返回值200，表示查看好友成功** { "action": "get", "uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/contacts/users", "entities": [], "data": [ "user3", "user2" ], "timestamp": 1543819826513, "duration": 12, "count": 2 } **返回值404，表示此IM用户不存在** { "error": "service_resource_not_found", "timestamp": 1542599741965, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542599778401, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 获取黑名单 ==== 获取 IM 用户的黑名单。 === HTTP Request === ^{{:im:server:ready:get.png?nolink&90|}}^**/{org_name}/{app_name}/users/{owner_username}/blocks/users**^ 需要在请求时对应填写{owner_username}，获取黑名单的用户名 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Response Body === ^参数^说明^ |username|“user1”, “user2”，获取到的黑名单列表| === 请求示例 === curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/blocks/users' === 可能返回的结果示例 === **返回值200，表示查看用户黑名单成功** { "action": "get", "uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/blocks/users", "entities": [], "data": [ "user2" ], "timestamp": 1542599978751, "duration": 4, "count": 1 } **返回值404，表示此IM用户不存在** { "error": "service_resource_not_found", "timestamp": 1542600037889, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542600068826, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 添加黑名单 ==== 向 IM 用户的黑名单列表中添加一个或者多个用户，黑名单中的用户无法给该 IM 用户发送消息，每个用户的黑名单人数上限为500。 === HTTP Request === ^{{:im:server:ready:post.png?nolink&90|}}^**/{org_name}/{app_name}/users/{owner_username}/blocks/users**^ 需要在请求时对应填写{owner_username}，要添加黑名单的用户名 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Request Body === ^参数^说明^ |usernames|“user1”, “user2”，需要加入到黑名单中的用户名以数组方式提交| === Response Body === 在返回值中查看data字段包含的信息 ^参数^说明^ |username|这里会把已添加至内名单的用户名进行展示| === 请求示例 === curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -d '{ "usernames": [ "user2" ] }' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/blocks/users' === 可能返回的结果示例 === **返回值200，表示添加黑名单成功** { "action": "post", "application": "8be024f0-e978-11e8-b697-5d598d5f8402", "uri": "https://a1.easemob.com/easemob-demo/testapp", "entities": [], "data": [ "user2" ], "timestamp": 1542600372046, "duration": 11, "organization": "easemob-demo", "applicationName": "testapp" } **返回值404，表示此IM用户不存在** { "error": "service_resource_not_found", "timestamp": 1542600419231, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } **返回值400，表示被添加的用户不存在** { "error": "illegal_argument", "timestamp": 1542600449246, "duration": 0, "exception": "java.lang.IllegalArgumentException", "error_description": "attempt to adding new block[user20] for user[user1],but user[user20] not found." } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542600528822, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:post:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 移除黑名单 ==== 从 IM 用户的黑名单中移除用户。将用户从黑名单移除后，恢复到好友，或者未添加好友的用户关系。可以正常的进行消息收发。 === HTTP Request === ^{{:im:server:ready:delete.png?nolink&90|}}^**/{org_name}/{app_name}/users/{owner_username}/blocks/users/{blocked_username}**^ 需要在请求时对应填写{owner_username}，要移除黑名单的用户名 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Response Body === ^参数^说明^ |entities|从黑名单中移除的 IM 用户的详细信息| === 请求示例 === curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/blocks/users/user2' === 可能返回的结果示例 === **返回值200，表示移出黑名单成功** { "action": "delete", "application": "8be024f0-e978-11e8-b697-5d598d5f8402", "path": "/users/4759aa70-eba5-11e8-925f-6fa0510823ba/blocks", "uri": "https://a1.easemob.com/easemob-demo/testapp/users/4759aa70-eba5-11e8-925f-6fa0510823ba/blocks", "entities": [ { "uuid": "b2aade90-e978-11e8-a974-f3368f82e4f1", "type": "user", "created": 1542356523769, "modified": 1542597334500, "username": "user2", "activated": true, "nickname": "testuser" } ], "timestamp": 1542600712985, "duration": 20, "organization": "easemob-demo", "applicationName": "testapp" } **返回值404，表示此IM用户或被减的用户不存在** { "error": "service_resource_not_found", "timestamp": 1542600858000, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542600910575, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:delete:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- =====在线与离线===== 环信提供多个接口，可以查看用户的在线/离线状态，用户的消息的在线/离线状态和数量。 ^名称^请求^描述^ |获取用户在线状态|/{org_name}/{app_name}/users/{username}/status|查看一个用户的在线状态| |批量获取用户在线状态|/{org_name}/{app_name}/users/batch/status|批量查看用户的在线状态| |获取离线消息数|/{org_name}/{app_name}/users/{owner_username}/offline_msg_count|获取一个 IM 用户的离线消息数 | |获取离线消息的状态|/{org_name}/{app_name}/users/{username}/offline_msg_status/{msg_id}|通过离线消息的 ID 查看用户的该条离线消息状态| ==== 获取用户在线状态 ==== 查看一个用户的在线状态。 === HTTP Request === ^{{:im:server:ready:get.png?nolink&90|}}^**/{org_name}/{app_name}/users/{username}/status**^ 需要在请求时对应填写{username}，要获取在线状态的用户名。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Response Body === 在返回值中查看data字段包含的信息 ^参数^说明^ |username|会显示为“user1”对应就是查询的username，“offline”代表离线，“online”在表用户当前在线| === 请求示例 === curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/status' === 可能返回的结果示例 === **返回值200，表示查询用户状态成功** { "action": "get", "uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/status", "entities": [], "data": { "user1": "offline" }, "timestamp": 1542601284531, "duration": 4, "count": 0 } **返回值404，表示此IM用户不存在** { "error": "service_resource_not_found", "timestamp": 1542601345042, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542601375113, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 批量获取用户在线状态 ==== 批量查看用户的在线状态，最大同时查看100个用户。 === HTTP Request === ^{{:im:server:ready:post.png?nolink&90|}}^**/{org_name}/{app_name}/users/batch/status**^ === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Request Body === ^参数^说明^ |usernames|“user1”, “user2”，需要查询状态的用户名以数组方式提交，最多不能超过100个| === Response Body === 在返回值中查看data字段包含的信息 ^参数^说明^ |username|会显示为“user1”对应就是查询的username，“offline”代表离线，“online”在表用户当前在线| === 请求示例 === curl -X POST http://a1.easemob.com/easemob-demo/chatdemoui/users/batch/status -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -H 'Content-Type: application/json' -d '{"usernames":["user1","user2"]}' === 可能返回的结果示例 === **返回值200，表示查询用户状态成功** 如果请求输入错误的用户名，即请求不存在的用户状态，则返回的参数一定是offline，此接口不对用户名进行校验。 { "action": "get batch user status", "data": [ { "user1": "offline" }, { "user2": "offline" } ], "timestamp": 1552280231926, "duration": 4 } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542601375113, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试；或者或者请求的用户数大于100，请重新发送正确数量的请求。详见[[im:server:help:restastrict|接口限流说明]] ---- ==== 获取用户离线消息数 ==== 获取 IM 用户的离线消息数量。 === HTTP Request === ^{{:im:server:ready:get.png?nolink&90|}}^**/{org_name}/{app_name}/users/{owner_username}/offline_msg_count**^ 需要在请求时对应填写{owner_username}，要获取离线消息数的用户名。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Response Body === 在返回值中查看data字段包含的信息 ^参数^说明^ |username|会显示为“user1”对应就是查询的username，“数字”当前离线消息的数量| === 请求示例 === curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/offline_msg_count' === 可能返回的结果示例 === **返回值200，表示查询离线消息数成功** { "action": "get", "uri": "http://tomcatcluster_users/easemob-demo/testapp/users/user1/offline_msg_count", "entities": [], "data": { "user1": 0 }, "timestamp": 1542601518137, "duration": 3, "count": 0 } **返回值404，表示此IM用户不存在** { "error": "service_resource_not_found", "timestamp": 1542601576537, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542601604510, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 获取某条离线消息状态 ==== 获取 IM 用户的离线消息状态，查看用户的离线消息离线消息的状态 === HTTP Request === ^{{:im:server:ready:get.png?nolink&90|}}^**/{org_name}/{app_name}/users/{username}/offline_msg_status/{msg_id}**^ 需要在请求时对应填写{username}，要获取离线消息状态的用户名。{msg_id}，要查看离线消息状态的ID。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Response Body === 在返回值中查看data字段包含的信息 ^参数^说明^ |msg_id|"对应的ID编号"，表示为对应的消息id， "delivered"表示状态为消息已投递，"undelivered"表示消息未投递| === 请求示例 === curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/offline_msg_status/123' === 可能返回的结果示例 === **返回值200，表示查询离线消息状态成功** { "action": "get", "uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/offline_msg_status/123", "entities": [], "data": { "123": "delivered" }, "timestamp": 1542601830084, "duration": 5, "count": 0 } **返回值404，表示此IM用户不存在** { "error": "service_resource_not_found", "timestamp": 1542601878917, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542601903781, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- =====账号禁用与解禁===== 环信提供了对 IM 用户的禁用以及解禁接口操作，对用户禁用用户将立即下线并无法登录进入环信，直到被解禁后才能恢复登录。常用在对异常用户的即时处理场景使用。 ^名称^请求^描述^ |用户账号禁用|/{org_name}/{app_name}/users/{username}/deactivate|禁用用户的登录账号，必须通过解禁才能恢复| |用户账号解禁| /{org_name}/{app_name}/users/{username}/activate|解禁后用户恢复正常使用| ==== 用户账号禁用 ==== 禁用某个 IM 用户的账号，禁用后该用户不可登录，下次解禁后该账户恢复正常使用。 === HTTP Request === ^{{:im:server:ready:post.png?nolink&90|}}^**/{org_name}/{app_name}/users/{username}/deactivate**^ 需要在请求时对应填写{username}，要禁用的用户名。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Response Body === 在返回值中查看entities字段包含的信息 ^参数^说明^ |uuid|用户的UUID，标识字段| |type|"user"用户类型| |username|用户名，也就是环信 ID | |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| === 请求示例 === curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/deactivate' === 可能返回的结果示例 === **返回值200，表示禁用用户账号成功** { "action": "Deactivate user", "entities": [ { "uuid": "4759aa70-eba5-11e8-925f-6fa0510823ba", "type": "user", "created": 1542595573399, "modified": 1542597578147, "username": "user1", "activated": false, "nickname": "user" } ], "timestamp": 1542602157258, "duration": 12 } **返回值400，表示此IM用户不存在** { "error": "management", "timestamp": 1542602213887, "duration": 0, "exception": "org.apache.usergrid.management.exceptions.ManagementException", "error_description": "User with id null does not exist in app 8be024f0-e978-11e8-b697-5d598d5f8402" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542602239851, "duration": 0, "exception": "org.apache.usergrid.rest.exceptions.SecurityException", "error_description": "No admin user access authorized" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ==== 用户账号解禁 ==== 解除 IM 用户账号的禁用操作，由禁用到解禁操作后，需要用户重新登录。 === HTTP Request === ^{{:im:server:ready:post.png?nolink&90|}}^**/{org_name}/{app_name}/users/{username}/activate**^ 需要在请求时对应填写{username}，要解禁的用户名。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Response Body === ^参数^说明^ |action|操作，“activate user"表示解禁/激活 IM 用户| === 请求示例 === curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/activate' === 可能返回的结果示例 === **返回值200，表示用户账号解禁成功** { "action": "activate user", "timestamp": 1542602404132, "duration": 9 } **返回值404，表示此IM用户不存在** { "error": "service_resource_not_found", "timestamp": 1542602447129, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542602487688, "duration": 0, "exception": "org.apache.usergrid.rest.exceptions.SecurityException", "error_description": "No admin user access authorized" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- ===== 强制下线 ===== 强制 IM 用户状态改为离线，用户需要重新登录才能正常使用。 === HTTP Request === ^{{:im:server:ready:get.png?nolink&90|}}^**/{org_name}/{app_name}/users/{username}/disconnect**^ 需要在请求时对应填写{username}，要强制下线的用户名。 === Request Headers === ^参数^说明^ |Content-Type|application/json| |Authorization|Bearer ${token}| === Response Body === 在返回值中查看data字段包含的信息 ^参数^说明^ |result|操作结果，“true"表示用户已经被强制下线| === 请求示例 === curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easemob.com/easemob-demo/testapp/users/user1/disconnect' === 可能返回的结果示例 === **返回值200，表示强制用户下线成功** { "action": "get", "uri": "http://a1.easemob.com/easemob-demo/testapp/users/user1/disconnect", "entities": [], "data": { "result": true }, "timestamp": 1542602601332, "duration": 6, "count": 0 } **返回值404，表示此IM用户不存在** { "error": "service_resource_not_found", "timestamp": 1542602640827, "duration": 0, "exception": "org.apache.usergrid.services.exceptions.ServiceResourceNotFoundException", "error_description": "Service resource not found" } **返回值401，表示未授权[无token、token错误、token过期]** { "error": "unauthorized", "timestamp": 1542602666575, "duration": 0, "exception": "org.apache.shiro.authz.UnauthorizedException", "error_description": "Subject does not have permission [applications:get:8be024f0-e978-11e8-b697-5d598d5f8402:/users/4759aa70-eba5-11e8-925f-6fa0510823ba]" } 如果返回结果是429、503或者其他5xx，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] ---- 上一页：[[im:server:ready:releasenote|版本更新]] 下一页：[[im:server:basics:messages|发送消息]]