用户(user)对象结构

字段

参数类型说明
user_idinteger用户 ID
avatarstring用户头像
_usernamestring用户名
_emailstring用户邮件地址
_email_verifiedboolean用户邮件地址是否已经验证
_providerobject用户在平台方的用户信息(见 v2.0/user/info 接口)以及其他 _userprofile 表的内置字段及用户自定义字段
countrystring用户所在的国家
provincestring用户所在的省份
citystring用户所在城市
genderstring用户的性别,值为 1 时是男性,值为 2 时是女性,值为 0 时是未知

示例

  1. {
  2. "_email": "hgzchn@qq.com",
  3. "_email_verified": false,
  4. "_provider": {},
  5. "avatar": "https://media.ifanrusercontent.com/hydrogen/default_avatar.png",
  6. "id": 34719381111111,
  7. "user_id": 3471938111111,
  8. "country": "China",
  9. "province": "Guangdong",
  10. "city": "Guangzhou",
  11. "gender": 1
  12. }

用户注册

接口

POST /hserve/v2.1/register/:register-type/

:register-type 有两种:

  • email: 通过邮箱注册
  • username: 通过用户名注册

请求参数

参数类型必填说明
emailstring邮箱地址
passwordstring密码

请求示例

  1. curl -X POST \
  2. -H "X-Hydrogen-Client-ID: [[client_id]]" \
  3. -H "Content-Type: application/json" \
  4. -d '{"email":"hegz@qq.com","password":"mbbmb*cb"}' \
  5. https://{{服务器域名}}/hserve/v2.1/register/email/

请求参数

参数类型必填说明
usernamestring用户名
passwordstring密码

请求示例

  1. curl -X POST \
  2. -H "X-Hydrogen-Client-ID: [[client_id]]" \
  3. -H "Content-Type: application/json" \
  4. -d '{"username":"hegz","password":"mbbmb*cb"}' \
  5. https://{{服务器域名}}/hserve/v2.1/register/username/

返回参数说明

参数类型说明
tokenstringUser authentication token
expires_inintegertoken 的有效时间,最长为 30 天,单位:秒;token 过期时间 = 注册时间 + token 有效时间

其余字段可参考用户(user)

状态码说明

201: 注册成功

400: 参数错误

用户登录

接口

POST /hserve/v2.1/login/:login-type/

:login-type 有两种:

  • email: 通过邮箱登陆
  • username: 通过用户名登陆

请求参数

参数类型必填说明
emailstring邮箱地址
passwordstring密码

请求示例

  1. curl -X POST \
  2. -H "X-Hydrogen-Client-ID: [[client_id]]" \
  3. -H "Content-Type: application/json" \
  4. -d '{"email":"hegz@qq.com","password":"mbbmb*cb"}' \
  5. https://{{服务器域名}}/hserve/v2.1/login/email/

请求参数

参数类型必填说明
usernamestring用户名
passwordstring密码

请求示例

  1. curl -X POST \
  2. -H "X-Hydrogen-Client-ID: [[client_id]]" \
  3. -H "Content-Type: application/json" \
  4. -d '{"username":"hegz","password":"mbbmb*cb"}' \
  5. https://{{服务器域名}}/hserve/v2.1/login/username/

返回示例

参数类型说明
tokenstringUser authentication token
expires_inintegertoken 的有效时间,最长为 30 天,单位:秒;token 过期时间 = 登录时间 + token 有效时间

其余字段可参考用户(user)

状态码说明

201: 登陆成功

400: 参数错误

查询用户信息

接口

GET /hserve/v2.2/user/info/:user_id/

:user_id用户(user)中的 user_id

请求示例

  1. curl -X GET \
  2. -H "X-Hydrogen-Client-ID: [[client_id]]" \
  3. -H "Authorization: Hydrogen-r1 {{AccessToken}}" \
  4. -H "Content-Type: application/json" \
  5. https://{{服务器域名}}/hserve/v2.2/user/info/72818312393/

返回示例

  1. {
  2. "country": "China",
  3. "avatar": "https://media.ifanrusercontent.com/blablabla.jpg",
  4. "gender": 1,
  5. "unionid": null,
  6. "age": 40,
  7. "created_at": 1513088820,
  8. "id": 72818312393,
  9. "custom_name": "custom_default_value",
  10. "nickname": "hgz",
  11. "updated_at": 1531543768,
  12. "is_authorized": true,
  13. "_provider": {},
  14. "openid": "oXUfx0HKez4xxxxxxxx-xxxxxxx",
  15. "created_by": 36395395,
  16. "province": "Guangdong",
  17. "city": "Guangzhou"
  18. }

字段详细说明请参考用户(user)

状态码说明

200: 查询成功

401: 未授权,请检查请求头中的 Authorization 字段是否正确

404: 用户不存在

批量查询用户信息

接口

GET /hserve/v2.2/user/info/

该接口支持通过参数 return_total_count 指定是否返回查询对象总数,以协助不关心对象总数只关心查询结果列表的开发者提升接口响应速度。同时,从 v2.2 版本开始该接口默认不返回查询对象总数,欲获取总数的开发者需要显式指定 return_total_count 参数。

若开发者只需要获取对象总数,则可以通过设置 limit=1 以及 return_total_count=1 来达到该效果,total_count 可从返回的 meta 中获取

请求示例:

  1. https://{{服务器域名}}/hserve/v2.2/user/info/?limit=1&return_total_count=1

请求示例

  1. curl -X GET \
  2. -H "X-Hydrogen-Client-ID: [[client_id]]" \
  3. -H "Authorization: Hydrogen-r1 {{AccessToken}}" \
  4. -H "Content-Type: application/json" \
  5. https://{{服务器域名}}/hserve/v2.2/user/info/

返回示例

  1. {
  2. "objects": [
  3. {
  4. "country": "China",
  5. "avatar": "https://media.ifanrusercontent.com/blablabla.jpg",
  6. "gender": 1,
  7. "unionid": null,
  8. "age": 40,
  9. "created_at": 1513088820,
  10. "id": 30000000,
  11. "custom_name": "custom_default_value",
  12. "nickname": "hgz",
  13. "updated_at": 1531543768,
  14. "is_authorized": true,
  15. "_provider": {},
  16. "openid": "oXUfx0HKez4xxxxxxxx-xxxxxxx",
  17. "created_by": 36395395,
  18. "province": "Guangdong",
  19. "city": "Guangzhou"
  20. }
  21. ],
  22. "meta": {
  23. "total_count": 140,
  24. "limit": 1,
  25. "previous": null,
  26. "next": "/userve/v2.2/user/info/?limit=1&offset=1",
  27. "offset": 0
  28. }
  29. }

字段的详细请参考用户(user)

状态码说明

200: 查询成功

401: 未授权,请检查请求头中的 Authorization 字段是否正确

404: 用户不存在

用户邮箱验证

接口

POST /hserve/v2.0/user/email-verify/

请求示例

  1. curl -X POST \
  2. -H "X-Hydrogen-Client-ID: [[client_id]]" \
  3. -H "Authorization: Hydrogen-r1 {{AccessToken}}" \
  4. -H "Content-Type: application/json" \
  5. https://{{服务器域名}}/hserve/v2.0/user/email-verify/

返回示例

  1. {
  2. "status": "ok"
  3. }

状态码说明

201: 成功发送验证邮件

400: 发送失败

401: 未授权,请检查请求头中的 Authorization 字段是否正确

用户登出

接口

POST /hserve/v2.0/session/destroy/

请求示例

  1. curl -X POST \
  2. -H "X-Hydrogen-Client-ID: [[client_id]]" \
  3. -H "Authorization: Hydrogen-r1 {{AccessToken}}" \
  4. -H "Content-Type: application/json" \
  5. -d "{}" \
  6. https://{{服务器域名}}/hserve/v2.0/session/destroy/

返回示例

  1. {
  2. "message": "Destroy succeed.",
  3. "status": "ok"
  4. }

状态码说明

201: 登出成功

401: 未授权,请检查请求头中的 Authorization 字段是否正确

修改用户信息

可更改密码、用户名、邮箱、手机号

接口

PUT /hserve/v2.1/user/account/

请求参数

参数类型必填说明
emailstring新的邮箱地址
usernamestring新的用户名
phonestring新的手机号
passwordstring旧密码
new_passwordstring新密码

如果选择修改密码, 必须同时传入 passwordnew_password。当设置新的手机号时,phone_verified 重置为 false,需要重新通过验证码进行验证。

如想重置用户的 email/username/phone,可以将 email/username/phone 的值设置为 null。

请求示例

  1. curl -X PUT \
  2. -H "X-Hydrogen-Client-ID: [[client_id]]" \
  3. -H "Authorization: Hydrogen-r1 {{AccessToken}}" \
  4. -H "Content-Type: application/json" \
  5. -d '{"password": "oldpassword", "new_password": "new_password"}' \
  6. https://{{服务器域名}}/hserve/v2.1/user/account/

返回示例

  1. {
  2. "email": "hgzchn@qq.com",
  3. "email_verified": false,
  4. "username": "123",
  5. "phone": "13800138000",
  6. "phone_verified": true
  7. }

返回字段说明

参数类型说明
emailstring目前的邮箱
email_verifiedboolean邮箱是否已经验证
usernamestring目前的用户名
phonestring手机号码
phone_verifiedboolean手机号码是否已经验证

状态码说明

200: 更新成功

400: 参数错误(可能是旧密码错误)

401: 未授权,请检查请求头中的 Authorization 字段是否正确

用户通过邮箱重置密码

接口

POST /hserve/v2.0/user/password/reset/

请求参数

参数类型必填说明
emailstring需要重置密码的用户的邮箱地址

请求示例

  1. curl -X POST \
  2. -H "X-Hydrogen-Client-ID: [[client_id]]" \
  3. -H "Content-Type: application/json" \
  4. -d '{"email":"hgzchn@qq.com"}' \
  5. https://{{服务器域名}}/hserve/v2.0/user/password/reset/

返回示例

  1. {
  2. "status": "ok"
  3. }

状态码说明

201: 已向用户发送密码重置邮件

400: 参数错误

404: 用户不存在