差别
这里会显示出您选择的修订版和当前版本之间的差别。
| 两侧同时换到之前的修订记录 前一修订版 后一修订版 | 前一修订版 | ||
|
im:server:ready:user [2019/03/11 11:53] she |
im:server:ready:user [2022/04/27 09:00] (当前版本) jennifer.zeng |
||
|---|---|---|---|
| 行 1: | 行 1: | ||
| ====== 用户体系集成 ====== | ====== 用户体系集成 ====== | ||
| - | ---- | + | 更新时间：2021-12-31 该文档已不再维护，请看新版 3.X 文档。 |
| + | 新版文档见：[[ccim:rest:accountsystem|用户体系集成]]。 | ||
| + | |||
| + | ---- | ||
| ===== 概述 ===== | ===== 概述 ===== | ||
| - | 介绍 Appkey 和环信 ID 的数据结构以及使用规则。 | + | 介绍 AppKey 和环信 ID 的数据结构以及使用规则。 |
| ==== Appkey 数据结构 ==== | ==== 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** 格式的字符串，字符串只能由小写字母数字组成，AppKey 是环信应用的唯一标识。前半部分 **org_name** 是在多租户体系下的唯一租户标识，后半部分 **app_name** 是租户下的 App 唯一标识（在环信后台创建一个 App 时填写的应用 ID 即是 app_name ）。下述的 REST API 中，**/{org_name}/{app_name}** 的请求，均是针对一个唯一的 AppKey 进行的。目前环信注册的 AppKey 暂不能由用户自己完成删除操作，如果对 APP 删除需要联系环信操作完成。 |
| - | ^Appkey ^xxxx ^分隔符 ^xxxx^ | + | ^Appkey ^xxxx ^分隔符 ^xxxx ^描述^ |
| - | |环信应用的唯一标识|org_name |#|app_name| | + | |环信应用的唯一标识|org_name |#|app_name| app_name 只能是字母、数字、横线组合。长度不能超过 32 字符。| |
| 行 19: | 行 22: | ||
| 环信作为一个聊天通道，只需要提供环信 ID （也就是 IM 用户名）和密码就够了。 | 环信作为一个聊天通道，只需要提供环信 ID （也就是 IM 用户名）和密码就够了。 | ||
| ^名称 ^字段名 ^数据类型 ^描述^ | ^名称 ^字段名 ^数据类型 ^描述^ | ||
| - | |环信 ID |username |String |在 AppKey 的范围内唯一用户名。| | + | |环信 ID |username |String |在 AppKey 的范围内唯一用户名，用户 ID 的长度在 64 字节以内。| |
| |用户密码 |password |String |用户登录环信使用的密码。| | |用户密码 |password |String |用户登录环信使用的密码。| | ||
| 行 32: | 行 35: | ||
| * 不能使用 email 地址 | * 不能使用 email 地址 | ||
| * 不能使用 UUID | * 不能使用 UUID | ||
| - | * 用户ID的长度在255字节以内 | + | * 用户 ID 的长度在 64 字节以内 |
| * 中间不能有空格或者井号（#）等特殊字符 | * 中间不能有空格或者井号（#）等特殊字符 | ||
| - | * 允许的用户名正则 “[a-zA-Z0-9_-.]*”（a~z大小写字母/数字/下划线/横线/英文句号），其他都不允许 **如果是大写字母会自动转成小写** | + | * 允许的用户名正则 “[a-z0-9_-.]*”（a~z小写字母/数字/下划线/横线/英文句号），其他都不允许 **如果是大写字母会自动转成小写** |
| - | * 不区分大小写。系统忽略大小写，认为 AA、Aa、aa、aA 都是一样的。如果系统已经存在了环信 ID 为 AA 的用户，再试图使用 aa 作为环信 ID 注册新用户，系统返回用户名重复，以此类推。但是请注意：环信 ID 在数据上的表现形式还是用户最初注册的形式，注册时候使用的大写就保存大写，是小写就保存小写。即：使用 AA 注册，环信保存的 ID 就是 AA；使用 Aa 注册，环信保存的 ID 就是 Aa，以此类推。 | + | * 不区分大小写。系统忽略大小写，认为 AA、Aa、aa、aA 都是一样的。如果系统已经存在了环信 ID 为 AA 的用户，再试图使用 aa 作为环信 ID 注册新用户，系统返回用户名重复，以此类推, 因此建议用户使用小写字母，否则可能遇到一些异常情况。但是请注意：环信 ID 在数据上的表现形式还是用户最初注册的形式，注册时候使用的大写就保存大写，是小写就保存小写。即：使用 AA 注册，环信保存的 ID 就是 AA；使用 Aa 注册，环信保存的 ID 就是 Aa，以此类推。 |
| 另：本文档中可能会交错使用“环信 ID”和“环信用户名”两个术语，但是请注意，这里两个的意思是一样的。 | 另：本文档中可能会交错使用“环信 ID”和“环信用户名”两个术语，但是请注意，这里两个的意思是一样的。 | ||
| 行 49: | 行 52: | ||
| 介绍关于 IM 用户体系集成过程中，需要使用到的 REST API 文档详细说明，可以通过使用文档中嵌入的[[http://api-docs.easemob.com/|Easemob 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} 之类的这种参数需要替换成具体的值。 | 环信提供的 REST API 需要权限才能访问，权限通过发送 HTTP 请求时携带 token 来体现，下面描述获取 token 的方式。说明：API 描述的时候使用到的 {APP 的 client_id} 之类的这种参数需要替换成具体的值。 | ||
| - | **重要提醒：**获取 token 时服务器会返回 token 有效期，具体值参考接口返回的 expires_in 字段值。由于网络延迟等原因，系统不保证 token 在此值表示的有效期内绝对有效，如果发现 token 使用异常请重新获取新的 token，比如“http response code”返回 401。另外，请不要频繁向服务器发送获取 token 的请求，同一账号发送此请求超过一定频率会被服务器封号，切记，切记！！ | + | **重要提醒： |
| + | ** 获取 token 时服务器会返回 token 有效期，具体值参考接口返回的 expires_in 字段值。由于网络延迟等原因，系统不保证 token 在此值表示的有效期内绝对有效，如果发现 token 使用异常请重新获取新的 token，比如“http response code”返回 401。另外，请不要频繁向服务器发送获取 token 的请求，同一账号发送此请求超过一定频率会被服务器封号，切记，切记！！ | ||
| client_id 和 client_secret 可以在环信管理后台的 [[http://www.google.com|APP 详情页面]]看到。 | client_id 和 client_secret 可以在环信管理后台的 [[http://www.google.com|APP 详情页面]]看到。 | ||
| 行 72: | 行 101: | ||
| |client_id|App的client_id，可在[[https://console.easemob.com/app-detail/detail|app详情页找到]]| | |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详情页找到]]| | ||
| + | |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 === | === Response Body === | ||
| 行 77: | 行 108: | ||
| ^参数^说明^ | ^参数^说明^ | ||
| |access_token |有效的token字符串| | |access_token |有效的token字符串| | ||
| - | |expires_in |token 有效时间，以秒为单位，在有效期内不需要重复获取| | + | |expires_in |token 有效期，单位为秒(s)。| |
| |application |当前 App 的 UUID 值| | |application |当前 App 的 UUID 值| | ||
| 行 86: | 行 117: | ||
| "grant_type": "client_credentials", | "grant_type": "client_credentials", | ||
| "client_id": "YXA6i-Ak8Ol4Eei2l11ZjV-EAg", | "client_id": "YXA6i-Ak8Ol4Eei2l11ZjV-EAg", | ||
| - | "client_secret": "YXA6VunqiNxoB7IwXHInk1cGiXOOJfc" | + | "client_secret": "YXA6VunqiNxoB7IwXHInk1cGiXOOJfc", |
| + | "ttl": "1024000" | ||
| }' 'http://a1.easemob.com/easemob-demo/testapp/token' | }' 'http://a1.easemob.com/easemob-demo/testapp/token' | ||
| </code> | </code> | ||
| 行 105: | 行 137: | ||
| <code json> | <code json> | ||
| { | { | ||
| - | "error_description": "client_id does not match", | + | "access_token": "YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw", |
| - | "error": "invalid_grant" | + | "expires_in": 1024000, |
| + | "application": "8be024f0-e978-11e8-b697-5d598d5f8402" | ||
| } | } | ||
| </code> | </code> | ||
| 行 114: | 行 147: | ||
| [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] | [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] | ||
| ---- | ---- | ||
| + | |||
| + | |||
| ===== 用户管理 ===== | ===== 用户管理 ===== | ||
| 行 133: | 行 168: | ||
| * “授权注册”模式：注册环信账号时，必须携带管理员身份认证信息。推荐使用“授权注册”，这样可以防止某些已经获取了注册 URL 和知晓注册流程的人恶意向服务器大量注册垃圾用户。 | * “授权注册”模式：注册环信账号时，必须携带管理员身份认证信息。推荐使用“授权注册”，这样可以防止某些已经获取了注册 URL 和知晓注册流程的人恶意向服务器大量注册垃圾用户。 | ||
| - | **注意：**以下 API 中提到的 ${token} 是个变量，使用时需要替换成通过 APP 的 client_id 和 client_secret 获取到的 token。 | + | **注意：** |
| + | * 以下 API 中提到的 ${token} 是个变量，使用时需要替换成通过 APP 的 client_id 和 client_secret 获取到的 token。 | ||
| + | |||
| + | * 在注册环信 id 时，建议不要使用有序的 id 进行注册，防止其他人知道注册 id 的顺序，恶意发送大量的垃圾消息。 | ||
| + | |||
| + | * 服务器端给自己用户注册账号的同时，在调用环信的rest接口给用户在注册一个环信id与自己的用户绑定，并返回给客户端，客户端拿到自己服务器用户的账号密码登录后，在拿环信id密码在登录环信服务器。 | ||
| ==== 注册单个用户(开放) ==== | ==== 注册单个用户(开放) ==== | ||
| 行 151: | 行 192: | ||
| ^参数^说明^ | ^参数^说明^ | ||
| - | |username|环信 ID ;也就是 IM 用户名的唯一登录账号| | + | |username|环信 ID ;也就是 IM 用户名的唯一登录账号，长度不可超过64个字符长度| |
| - | |password|登录密码| | + | |password|登录密码，长度不可超过64个字符长度| |
| - | |nickname|昵称（可选），在 iOS Apns 推送时会使用的昵称| | + | |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 === | === Response Body === | ||
| 行 163: | 行 204: | ||
| |type|"user"用户类型| | |type|"user"用户类型| | ||
| |username|用户名，也就是环信 ID | | |username|用户名，也就是环信 ID | | ||
| - | |nickname|昵称，在 iOS Apns 推送时会使用的昵称，没有设置则不会返回| | + | |nickname|iOS推送昵称（可选），在 iOS Apns 推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，长度不可超过100个字符| |
| |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | ||
| 行 232: | 行 273: | ||
| ^参数^说明^ | ^参数^说明^ | ||
| - | |username|环信 ID ;也就是 IM 用户的唯一登录账号| | + | |username|环信 ID ;也就是 IM 用户的唯一登录账号，长度不可超过64个字符长度| |
| - | |password|登录密码| | + | |password|登录密码，长度不可超过64个字符长度| |
| - | |nickname|昵称（可选），在 iOS Apns 推送时会使用的昵称，没有设置返则不会返回| | + | |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 === | === Response Body === | ||
| 行 244: | 行 285: | ||
| |type|"user"用户类型| | |type|"user"用户类型| | ||
| |username|用户名，也就是环信 ID | | |username|用户名，也就是环信 ID | | ||
| - | |nickname|昵称，在 iOS Apns 推送时会使用的昵称，，没有设置返则不会返回| | + | |nickname|昵称（可选），在 iOS Apns 推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，环信是不保存用户昵称，头像等个人信息的，需要自己服务器保存并与给自己用户注册的IM用户名绑定| |
| |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | ||
| 行 331: | 行 372: | ||
| ^参数^说明^ | ^参数^说明^ | ||
| - | |username|环信 ID ;也就是 IM 用户的唯一登录账号| | + | |username|环信 ID ;也就是 IM 用户的唯一登录账号，长度不可超过64个字符| |
| - | |password|登录密码| | + | |password|登录密码，长度不可超过64个字符| |
| - | |nickname|昵称（可选），在 iOS Apns 推送时会使用的昵称| | + | |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 === | === Response Body === | ||
| 行 343: | 行 383: | ||
| |type|"user"用户类型| | |type|"user"用户类型| | ||
| |username|用户名，也就是环信 ID | | |username|用户名，也就是环信 ID | | ||
| - | |nickname|昵称，在 iOS Apns 推送时会使用的昵称，没有设置返则不会返回| | + | |nickname|昵称（可选），在 iOS Apns 推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，环信是不保存用户昵称，头像等个人信息的，需要自己服务器保存并与给自己用户注册的IM用户名绑定| |
| |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | ||
| - | === 请求示例 === | + | === 请求示例1 === |
| <code php> | <code php> | ||
| 行 362: | 行 402: | ||
| "application": "22bcffa0-8f86-11e6-9df8-516f6df68c6d", | "application": "22bcffa0-8f86-11e6-9df8-516f6df68c6d", | ||
| "path": "/users", | "path": "/users", | ||
| - | "uri": "https://a1.easemob.com/1122161011178276/testapp/users", | + | "uri": "https://a1.easemob.com/easemob-demo/testapp/users", |
| "entities": [ | "entities": [ | ||
| { | { | ||
| 行 384: | 行 424: | ||
| ], | ], | ||
| "timestamp": 1541587920714, | "timestamp": 1541587920714, | ||
| + | "data": [], | ||
| "duration": 0, | "duration": 0, | ||
| "organization": "1122161011178276", | "organization": "1122161011178276", | ||
| 行 390: | 行 431: | ||
| </code> | </code> | ||
| + | === 请求示例2 === | ||
| + | |||
| + | <code php> | ||
| + | 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"}]' | ||
| + | </code> | ||
| + | |||
| + | 当请求 body 中存在已经注册过的 user3 时，那么请求会成功并且user1、user2也会注册成功，response 中的 data 数组内是返回存在问题的用户。 | ||
| + | |||
| + | === 可能返回的结果示例 === | ||
| + | |||
| + | **返回值200，表示成功返回token** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | "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" | ||
| + | } | ||
| + | </code> | ||
| + | |||
| + | |||
| + | 如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[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：是否激活| | ||
| + | |||
| + | === 请求示例 === | ||
| + | |||
| + | <code php> | ||
| + | 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' | ||
| + | </code> | ||
| + | |||
| + | === 可能返回的结果示例 === | ||
| + | |||
| + | **返回值200，表示成功返回token** | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | "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 | ||
| + | } | ||
| + | } | ||
| + | </code> | ||
| + | |||
| + | **返回值400，表示 username 或 password 错误** | ||
| + | <code json> | ||
| + | { | ||
| + | "error": "invalid_grant", | ||
| + | "timestamp": 1637741269908, | ||
| + | "duration": 0, | ||
| + | "error_description": "invalid password" | ||
| + | } | ||
| + | </code> | ||
| 如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] | 如果返回结果是<wrap em>429、503</wrap>或者其他<wrap em>5xx</wrap>，有可能代表该接口被限流了，请稍微暂停一下并重试。详见[[im:server:help:restastrict|接口限流说明]] | ||
| 行 420: | 行 593: | ||
| |username|用户名，也就是环信 ID | | |username|用户名，也就是环信 ID | | ||
| |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | ||
| - | |nickname|昵称，在 iOS Apns 推送时会使用的昵称，没有设置返则不会返回| | + | |nickname|昵称（可选），在 iOS Apns 推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，环信是不保存用户昵称，头像等个人信息的，需要自己服务器保存并与给自己用户注册的IM用户名绑定| |
| - | |notification_no_disturbing|消息提醒方式，“true”仅通知，“false“通知以及消息详情，没有设置返则不会返回| | + | |notification_display_style|消息提醒方式，“0”仅通知，“1“通知以及消息详情，没有设置返不会返回| |
| - | |notification_display_style|免打扰的设置。"0"代表免打扰关闭，“1”免打扰开启，没有设置返则不会返回| | + | |notification_no_disturbing|免打扰的设置。"false"代表免打扰关闭，“true”免打扰开启，没有设置返不会返回| |
| - | |notification_no_disturbing_start|免打扰的开始时间。数字代表开始时间，例如“8”代表每日8:00开启免打扰，没有设置返则不会返回| | + | |notification_no_disturbing_start|免打扰的开始时间。数字代表开始时间，例如“8”代表每日8:00开启免打扰，没有设置则不会返回| |
| - | |notification_no_disturbing_end|免打扰的结束时间。数字代表结束时间，例如“18”代表每日18:00关闭免打扰，没有设置返则不会返回| | + | |notification_no_disturbing_end|免打扰的结束时间。数字代表结束时间，例如“18”代表每日18:00关闭免打扰，没有设置则不会返回| |
| - | |notifier_name|客户端推送证书名称，没有设置返则不会返回| | + | |notification_ignore_63112447328257|屏蔽/取消屏蔽群组消息的离线推送的设置。数字代表群组id，“true”已屏蔽，“false“未屏蔽，没有设置则不会返回| |
| + | |notifier_name|客户端推送证书名称，没有设置则不会返回| | ||
| + | |device_token|推送token，没有则不会返回| | ||
| 行 512: | 行 687: | ||
| |type|"user"用户类型| | |type|"user"用户类型| | ||
| |username|用户名，也就是环信 ID | | |username|用户名，也就是环信 ID | | ||
| - | |nickname|昵称，在 iOS Apns 推送时会使用的昵称，没有设置返则不会返回| | + | |nickname|昵称（可选），在 iOS Apns 推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，环信是不保存用户昵称，头像等个人信息的，需要自己服务器保存并与给自己用户注册的IM用户名绑定| |
| |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | ||
| - | |notification_no_disturbing|消息提醒方式，“true”仅通知，“false“通知以及消息详情，没有设置返则不会返回| | + | |notification_display_style|消息提醒方式，“true”仅通知，“false“通知以及消息详情，没有设置则不会返回| |
| - | |notification_display_style|免打扰的设置。"0"代表免打扰关闭，“1”免打扰开启，没有设置返则不会返回| | + | |notification_no_disturbing|免打扰的设置。"0"代表免打扰关闭，“1”免打扰开启，没有设置则不会返回| |
| - | |notification_no_disturbing_start|免打扰的开始时间。数字代表开始时间，例如“8”代表每日8:00开启免打扰，没有设置返则不会返回| | + | |notification_no_disturbing_start|免打扰的开始时间。数字代表开始时间，例如“8”代表每日8:00开启免打扰，没有设置则不会返回| |
| - | |notification_no_disturbing_end|免打扰的结束时间。数字代表结束时间，例如“18”代表每日18:00关闭免打扰，没有设置返则不会返回| | + | |notification_no_disturbing_end|免打扰的结束时间。数字代表结束时间，例如“18”代表每日18:00关闭免打扰，没有设置则不会返回| |
| - | |notifier_name|客户端推送证书名称，没有设置返则不会返回| | + | |notification_ignore_63112447328257|屏蔽/取消屏蔽群组消息的离线推送的设置。数字代表群组id，“true”已屏蔽，“false“未屏蔽，没有设置则不会返回| |
| + | |notifier_name|客户端推送证书名称，没有设置则不会返回| | ||
| + | |device_token|推送token，没有则不会返回| | ||
| - | > 不分页 | + | 不分页 |
| === 请求示例 === | === 请求示例 === | ||
| 行 526: | 行 703: | ||
| <code php> | <code php> | ||
| curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users?limit=2' | curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users?limit=2' | ||
| + | </code> | ||
| + | |||
| + | 使用返回的cursor获取下一页 | ||
| + | <code php> | ||
| + | curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer YWMt7CoyjusbEeixOi3iod4eDAAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnJlhJIwBPGgCqtjiyVnR209iyr8kNbhJhhanNQDdP9CMmpK2G-NIUOQ' 'http://a1.easemob.com/easemob-demo/testapp/users?limit=2&cursor=LTgzNDAxMjM3OToxTEFnNE9sNEVlaVQ0UEdhdmJNR2tB' | ||
| </code> | </code> | ||
| 行 646: | 行 828: | ||
| ==== 删除单个用户 ==== | ==== 删除单个用户 ==== | ||
| - | 删除一个用户，如果此用户时群组或者聊天室的群主owner，系统会同时删除这些群组和聊天室。请在操作时进行确认。 | + | 删除一个用户，如果此用户是群组或者聊天室的群主owner，系统会同时删除这些群组和聊天室。请在操作时进行确认。 |
| === HTTP Request === | === HTTP Request === | ||
| 行 730: | 行 912: | ||
| ^{{:im:server:ready:delete.png?nolink&90|}}^**/{org_name}/{app_name}/users**^ | ^{{:im:server:ready:delete.png?nolink&90|}}^**/{org_name}/{app_name}/users**^ | ||
| - | 需要在请求时对应填写{username}，需要删除的 IM 用户名。 | ||
| === Request Headers === | === Request Headers === | ||
| 行 864: | 行 1045: | ||
| ---- | ---- | ||
| - | ==== 设置推送消息显示昵称 ==== | + | ==== 设置推送昵称 ==== |
| - | 设置用户的推送昵称，在 iOS APNS 推送时使用。 | + | 设置用户的推送昵称，在离线推送时使用。 |
| === HTTP Request === | === HTTP Request === | ||
| ^{{:im:server:ready:put.png?nolink&90|}}^** /{org_name}/{app_name}/users/{username}**^ | ^{{:im:server:ready:put.png?nolink&90|}}^** /{org_name}/{app_name}/users/{username}**^ | ||
| - | 需要在请求时对应填写{username}，需要修改昵称的 IM 用户名。 | + | 需要在请求时对应填写{username}，需要修改推送昵称的 IM 用户名。 |
| === Request Headers === | === Request Headers === | ||
| 行 882: | 行 1063: | ||
| ^参数^说明^ | ^参数^说明^ | ||
| - | |nickname|将要改成的昵称信息| | + | |nickname|将要改成的推送昵称信息| |
| === Response Body === | === Response Body === | ||
| 行 892: | 行 1073: | ||
| |type|"user"用户类型| | |type|"user"用户类型| | ||
| |username|用户名，也就是环信 ID | | |username|用户名，也就是环信 ID | | ||
| - | |nickname|昵称，在 iOS Apns 推送时会使用的昵称| | + | |nickname|昵称（可选），在离线推送时会使用的昵称（仅在推送通知栏内显示的昵称），并不是用户个人信息的昵称，环信是不保存用户昵称，头像等个人信息的，需要自己服务器保存并与给自己用户注册的IM用户名绑定| |
| |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | ||
| 行 905: | 行 1086: | ||
| === 可能返回的结果示例 === | === 可能返回的结果示例 === | ||
| - | **返回值200，表示用户昵称修改成功** | + | **返回值200，表示用户推送昵称修改成功** |
| <code json> | <code json> | ||
| 行 979: | 行 1160: | ||
| ^参数^说明^ | ^参数^说明^ | ||
| - | |notification_no_disturbing|“true”仅通知，“false“通知以及消息详情| | + | |notification_display_style|“0”仅通知，“1“通知以及消息详情| |
| === Response Body === | === Response Body === | ||
| 行 990: | 行 1171: | ||
| |username|用户名，也就是环信 ID | | |username|用户名，也就是环信 ID | | ||
| |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | |activated|用户是否已激活，“true”已激活，“false“封禁，封禁需要通过解禁接口进行解禁，才能正常登录| | ||
| - | |notification_no_disturbing|消息提醒方式，“true”仅通知，“false“通知以及消息详情| | + | |notification_display_style|消息提醒方式，“0”仅通知，“1“通知以及消息详情| |
| === 请求示例 === | === 请求示例 === | ||
| 行 1035: | 行 1216: | ||
| ==== 设置免打扰 ==== | ==== 设置免打扰 ==== | ||
| - | 设置 IM 用户免打扰，在免打扰期间，用户将不会收到消息通知。 | + | 设置 IM 用户免打扰，在免打扰期间，用户将不会收到离线消息推送。 |
| === HTTP Request === | === HTTP Request === | ||
| 行 1051: | 行 1232: | ||
| ^参数^说明^ | ^参数^说明^ | ||
| - | |notification_no_disturbing|是否免打扰，"0"代表免打扰关闭，“1”免打扰开启| | + | |notification_no_disturbing|是否免打扰，false 代表免打扰关闭，true 免打扰开启| |
| |notification_no_disturbing_start|免打扰起始时间，单位是小时| | |notification_no_disturbing_start|免打扰起始时间，单位是小时| | ||
| |notification_no_disturbing_end|免打扰结束时间，单位是小时| | |notification_no_disturbing_end|免打扰结束时间，单位是小时| | ||
| 行 1127: | 行 1308: | ||
| ==== 添加好友 ==== | ==== 添加好友 ==== | ||
| - | 添加好友，好友必须是和自己在一个 APPkey 下的 IM 用户，每个用户的好友数量上限为1000。 | + | 添加好友，好友必须是和自己在一个 APPkey 下的 IM 用户，单用户ID可以添加的好友数量，请参考不同版本[[http://www.easemob.com/pricing/im|数量]] |
| === HTTP Request === | === HTTP Request === | ||
| 行 1523: | 行 1705: | ||
| === HTTP Request === | === HTTP Request === | ||
| - | ^{{:im:server:ready:delete.png?nolink&90|}}^**/{org_name}/{app_name}/users/{owner_username}/blocks/users**^ | + | ^{{:im:server:ready:delete.png?nolink&90|}}^**/{org_name}/{app_name}/users/{owner_username}/blocks/users/{blocked_username}**^ |
| 需要在请求时对应填写{owner_username}，要移除黑名单的用户名 | 需要在请求时对应填写{owner_username}，要移除黑名单的用户名 | ||
| 行 1532: | 行 1714: | ||
| |Authorization|Bearer ${token}| | |Authorization|Bearer ${token}| | ||
| - | === Request Body === | ||
| - | |||
| - | ^参数^说明^ | ||
| - | |username|“user1”, “user2”，需要移除黑名单中的用户名以数组方式提交| | ||
| === Response Body === | === Response Body === | ||
| 行 1685: | 行 1863: | ||
| ---- | ---- | ||
| ==== 批量获取用户在线状态 ==== | ==== 批量获取用户在线状态 ==== | ||
| - | 批量查看用户的在线状态，最大同时查看100个用户。<wrap em>当前接口暂未开通</wrap> | + | 批量查看用户的在线状态，最大同时查看100个用户。 |
| === HTTP Request === | === HTTP Request === | ||
| - | ^{{:im:server:ready:get.png?nolink&90|}}^**/{org_name}/{app_name}/users/batch/status**^ | + | ^{{:im:server:ready:post.png?nolink&90|}}^**/{org_name}/{app_name}/users/batch/status**^ |
| === Request Headers === | === Request Headers === | ||
| 行 1712: | 行 1890: | ||
| <code php> | <code php> | ||
| - | 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”]}' | + | 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"]}' |
| </code> | </code> | ||
| 行 1754: | 行 1932: | ||
| ==== 获取用户离线消息数 ==== | ==== 获取用户离线消息数 ==== | ||
| - | 获取 IM 用户的离线消息数量。默认的离线消息数量上限为1200条。 | + | 获取 IM 用户的离线消息数量。 |
| === HTTP Request === | === HTTP Request === | ||
| 行 1864: | 行 2042: | ||
| "entities": [], | "entities": [], | ||
| "data": { | "data": { | ||
| - | "testmessage": "delivered" | + | "123": "delivered" |
| }, | }, | ||
| "timestamp": 1542601830084, | "timestamp": 1542601830084, | ||
| 行 2122: | 行 2300: | ||
| [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] | [[http://api-docs.easemob.com/|使用 Easemob REST API 在线测试]] | ||
| + | ---- | ||
| - | |||
| - | ---- | ||
| <WRAP group> | <WRAP group> | ||
| <WRAP half column> | <WRAP half column> | ||