差别
这里会显示出您选择的修订版和当前版本之间的差别。
两侧同时换到之前的修订记录 前一修订版 后一修订版 | 前一修订版 | ||
im:server:ready:user [2019/03/28 02:25] 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 === | ||
行 1689: | 行 1867: | ||
=== 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> |