内建账户 REST API
URL | HTTP | 功能 |
---|---|---|
/1.1/users | POST | 用户注册 用户连接 |
/1.1/usersByMobilePhone | POST | 使用手机号码注册或登录 |
/1.1/login | POST | 用户登录 |
/1.1/users/<objectId> | GET | 获取用户 |
/1.1/users/me | GET | 根据 sessionToken 获取用户信息 |
/1.1/users/<objectId>/refreshSessionToken | PUT | 重置用户 sessionToken |
/1.1/users/<objectId>/updatePassword | PUT | 更新密码,要求输入旧密码 |
/1.1/users/<objectId> | PUT | 更新用户 用户连接 验证 Email |
/1.1/users | GET | 查询用户 |
/1.1/users/<objectId> | DELETE | 删除用户 |
/1.1/requestPasswordReset | POST | 请求密码重设 |
/1.1/requestEmailVerify | POST | 请求验证用户邮箱 |
不仅在移动应用上,还在其他系统中,很多应用都有一个统一的登录流程。通过 REST API 访问用户的账户让你可以简单实现这一功能。
通常来说,用户(类名 _User
)这个类的功能与其他的对象是相同的,比如都没有限制模式(Schema free)。User 对象和其他对象不同的是一个用户必须有用户名(username)和密码(password),密码会被自动地加密和存储。
username 和 email 这两个字段必须是没有重复的(大小写敏感)。
注册
注册一个新用户与创建一个新的普通对象之间的不同点在于 username 和 password 字段都是必需的。password 字段会以和其他的字段不一样的方式处理,它在储存时会被加密而且永远不会被返回给任何来自客户端的请求。
你可以让云服务自动验证邮件地址,做法是进入 云服务控制台 > 存储 > 设置 > 用户账号,勾选 用户注册时,发送验证邮件。
这项设置启用了的话,所有填写了 email 的用户在注册时都会产生一个 email 验证地址,并发回到用户邮箱,用户打开邮箱点击了验证链接之后,用户表里 emailVerified
属性值会被设为 true。你可以在 emailVerified
字段上查看用户的 email 是否已经通过验证。
你还可以在 云服务控制台 > 存储 > 设置 > 用户账号,勾选未验证邮箱的用户,禁止登录。
为了注册一个新的用户,需要向 user 路径发送一个 POST 请求,你可以加入一个新的字段,例如,创建一个新的用户有一个电话号码:
curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
-H "Content-Type: application/json" \
-d '{"username":"tom","password":"f32@ds*@&dsa","phone":"18612340000"}' \
https://{{host}}/1.1/users
当创建成功时,HTTP 返回为 201 Created,Location 头包含了新用户的 URL:
Status: 201 Created
Location: https://{{host}}/1.1/users/55a47496e4b05001a7732c5f
返回的主体是一个 JSON 对象,包含 objectId、createdAt 时间戳表示创建对象时间,sessionToken 可以被用来认证这名用户随后的请求:
{
"sessionToken":"qmdj8pdidnmyzp0c7yqil91oc",
"createdAt":"2015-07-14T02:31:50.100Z",
"objectId":"55a47496e4b05001a7732c5f"
}
登录
在你允许用户注册之后,在以后你需要让他们用自己的用户名和密码登录。为了做到这一点,发送一个 POST 请求到 /1.1/login
,加上 username 和 password 作为 body。
curl -X POST \
-H "Content-Type: application/json" \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
-d '{"username":"tom","password":"f32@ds*@&dsa"}' \
https://{{host}}/1.1/login
用户也可以通过邮箱地址和密码登录,只需将 body 中的 username 换成 email:
{ "email": "tom@example.com", "password": "f32@ds*@&dsa" }
类似地,将 username
换成 mobilePhoneNumber
可以通过手机号和密码登录:
{ "mobilePhoneNumber": "+86186xxxxxxxx", "password": "f32@ds*@&dsa" }
返回的主体是一个 JSON 对象包括所有除了 password 以外的自定义字段。它同样包含了 createdAt、updateAt、objectId 和 sessionToken 字段。
{
"sessionToken": "qmdj8pdidnmyzp0c7yqil91oc",
"updatedAt": "2015-07-14T02:31:50.100Z",
"phone": "18612340000",
"objectId": "55a47496e4b05001a7732c5f",
"username": "tom",
"createdAt": "2015-07-14T02:31:50.100Z",
"emailVerified": false,
"mobilePhoneVerified": false
}
可以将 sessionToken 理解为用户的登录凭证,每个用户的 sessionToken 在同一个应用内都是唯一的, 类似于 Cookie 的概念。 SDK 在客户端会一直缓存 sessionToken,直到用户登出或重新登录。
正常情况下,用户的 sessionToken 是固定不变的,但在以下情况下会发生改变:
- 客户端调用了忘记密码功能,重设了密码。
- 开发者在 云服务控制台 > 存储 > 设置 > 用户账号 中勾选了 密码修改后,强制客户端重新登录,那么在修改密码后 sessionToken 也将强制更换。
- 调用
refreshSessionToken
主动重置。
在 sessionToken 变化后,已有的登录如果调用到用户相关权限受限的 API,将返回 403 权限错误。
重置登录 sessionToken
可以主动重置用户的 sessionToken:
curl -X PUT \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
-H "X-LC-Session: qmdj8pdidnmyzp0c7yqil91oc" \
https://{{host}}/1.1/users/57e3bcca67f35600577c3063/refreshSessionToken
调用这个 API 要求传入登录返回的 X-LC-Session
作为认证,或者使用 Master Key
。
重置成功将返回新的 sessionToken 及用户信息:
{
"sessionToken": "5frlikqlwzx1nh3wzsdtfr4q7",
"updatedAt": "2016-10-20T03:10:57.926Z",
"objectId": "57e3bcca67f35600577c3063",
"username": "tom",
"createdAt": "2016-09-22T11:13:14.842Z",
"emailVerified": false,
"mobilePhoneVerified": false
}
账户锁定
输入错误的密码或验证码会导致用户登录失败。如果在 15 分钟内,同一个用户登录失败的次数大于 6 次,该用户账户即被云端暂时锁定,此时云端会返回错误码 {"code":219,"error":"登录失败次数超过限制,请稍候再试,或者通过忘记密码重设密码。"}
,开发者可在客户端进行必要提示。
锁定将在最后一次错误登录的 15 分钟之后由云端自动解除,开发者无法通过 SDK 或 REST API 进行干预。在锁定期间,即使用户输入了正确的验证信息也不允许登录。这个限制在 SDK 和云引擎中都有效。
验证 Email
设置 email 验证是 app 设置中的一个选项,通过这个标识,应用层可以对提供真实 email 的用户更好的功能或者体验。Email 验证会在 User 对象中加入 emailVerified
字段,当一个用户的 email 被新设置或者修改过的话,emailVerified
会被重置为 false。云服务会往用户填写的邮箱发送一个验证链接,用户点击这个链接可以让 emailVerified
被设置为 true。
emailVerified 字段有 3 种状态可以参考:
- true:用户已经点击了发送到邮箱的验证地址,邮箱被验证为真实有效。云端保证在新创建用户的时候 emailVerified 一定为 false。
- false:User 对象最后一次被更新的时候,用户并没有确认过他的 email 地址。如果你看到 emailVerified 为 false 的话,你 可以考虑刷新 User 对象或者再次请求验证用户邮箱。
- null:User 对象在 email 验证没有打开的时候就已经创建了,或者 User 没有 email。
邮件模板和验证链接可以在云服务控制台 > 数据存储 > 用户 > 邮件模板定制。
请求验证 Email
发送给用户的邮箱验证邮件在一周内失效,你可以通过调用 /1.1/requestEmailVerify
来强制重新发送:
curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
-H "Content-Type: application/json" \
-d '{"email":"tom@example.com"}' \
https://{{host}}/1.1/requestEmailVerify
请求密码重设
在用户将 email 与他们的账户关联起来之后,你可以通过邮件来重设密码。操作方法为,发送一个 POST 请求到 /1.1/requestPasswordReset
,同时在 request 的 body 部分带上 email 字段。
curl -X POST \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
-H "Content-Type: application/json" \
-d '{"email":"tom@example.com"}' \
https://{{host}}/1.1/requestPasswordReset
如果成功的话,将返回状态码 200 OK
。
邮件模板和验证链接可以在云服务控制台 > 数据存储 > 用户 > 邮件模板定制。
获取用户
和获取对象类似,你可以发送一个 GET 请求到 URL 以获取用户的账户信息。比如,为了获取上面创建的用户:
curl -X GET \
-H "X-LC-Id: {{appid}}" \
-H "X-LC-Key: {{appkey}}" \
https://{{host}}/1.1/users/55a47496e4b05001a7732c5f