Smarthome API 说明文档

版本: 1.0

发布日期: 2024-03-28

历史记录

修订日期	版本	作者	说明
2024-3-28	V1.0	alva.huang	初始版本

[toc]

前言

概述

本文档旨在说明爱智居服务端的API接口，帮助开发人员如何使用smarthome api 进行开发，并详细介绍了各API的功能，调用方式，返回结果和错误码。

范围说明

此开发文档只针对智能家居控制app，小程序，以及相应的控制端app，面板app等的开发。

账户系统

账户系统主要功能是用户注册，登录，修改密码，忘记密码，注销账号。用户信息维护和更新。用户权限控制。角色映射等和用户相关的功能。

HTTP返回状态码说明

200-299 请求成功 400-499 请求失败，客户端参数或信息错误 500-599 请求失败，服务端错误

状态码	说明
200	请求成功
201	新增成功
204	删除成功/更新成功
401	请求失败，无权限，没有登陆认证或认证token错误
403	请求失败，无权限
404	请求失败，资源不存在
405	请求失败，请求方法不支持
406	请求失败，参数错误
400	请求失败，参数错误
408	请求失败，请求超时
415	请求失败，不支持的媒体类型
500	请求失败，服务端内部错误

用户登陆认证

微信用户注册登陆接口

用户通过微信小程序登陆，并使用微信code换取token，调用此接口完成注册和登录。当用户第一次使用微信小程序登陆，并且没有绑定过账号时，需要传入手机号码和验证码，进行注册绑定手机号码。后续使用微信小程序登陆，不需要传入手机号码和验证码。

POST 请求URL： https://account.izhiju.cn/realms/zhiju/protocol/openid-connect/token

请求头参数： Content-Type: application/x-www-form-urlencoded

请求体参数：

参数名	参数类型	默认值	说明
client_id	string	wechatapp	客户端id，微信小程序固定为wechatapp，必须字段
client_secret	string	平台相关的密钥	客户端密钥，必须字段
grant_type	string	password	授权类型，固定为password，必须字段
wechatCode	string	code	wx.login()返回的code,必须传值
smsCode	string	NULL	手机收到的验证码，已绑定的用户可不传
phoneNumber	string	NULL	手机号，可不传
areaCode	string	NULL	区号,可不传

返回结果：

成功，状态码200，返回如下内容：

{
  "access_token": "eyJhbGciO",  //token 可做为调用其它接口的授权凭证
  "expires_in": 1800,           //token有效期，单位秒
  "refresh_expires_in": 1800,   //refresh_token有效期，单位秒
  "refresh_token": "eyJhbGci",  //refresh_token，用于刷新token
  "token_type": "Bearer",       //token类型，Bearer
  "not-before-policy": 0,
  "session_state": "2f2bd023-793e-4abc-a067-7dd4d49705a3",
  "scope": "profile"     //token权限，profile表示用户信息
}

微信授权码无效，状态码401，返回如下内容：

{
  "error": "wechat_code_invalid",
  "error_description": "微信授权码无效，过期或已使用"
}

手机验证码错误，状态码401，返回如下内容：

{
  "error": "sms_code_invalid",
  "error_description": "手机验证码无效"
}

手机号已绑定其他账号，状态码401，返回如下内容：

{
  "error": "invalid_grant",
  "error_description": "Invalid user credentials"
}

客户端登陆认证接口

POST 请求URL： https://account.izhiju.cn/realms/zhiju/protocol/openid-connect/token

请求头参数： Content-Type: application/x-www-form-urlencoded

请求体参数：

参数名	参数类型	默认值	说明
client_id	string	wechatapp	客户端id，微信小程序固定为wechatapp，必须字段
client_secret	string	平台相关的密钥	客户端密钥，必须字段
grant_type	string	password	授权类型，固定为password，必须字段
username	string	username	用户名
password	string	user password	用户秘密

返回结果：

成功,状态码200

{
  "access_token": "eyJhbGciO",  //token 可做为调用其它接口的授权凭证
  "expires_in": 1800,           //token有效期，单位秒
  "refresh_expires_in": 1800,   //refresh_token有效期，单位秒
  "refresh_token": "eyJhbGci",  //refresh_token，用于刷新token
  "token_type": "Bearer",       //token类型，Bearer
  "not-before-policy": 0,
  "session_state": "2f2bd023-793e-4abc-a067-7dd4d49705a3",
  "scope": "profile"     //token权限，profile表示用户信息
}

客户端授权无效，用户名或秘密错误，状态码401

{
  "error": "invalid_grant",
  "error_description": "Invalid user credentials"
}

客户端id或secret错误，状态码401

{
  "error": "invalid_client",
  "error_description": "Invalid client or Invalid client credentials"
}

不支持的授权类型，状态码401

{
  "error": "unsupported_grant_type",
  "error_description": "Unsupported grant_type"
}

用户信息管理

获取用户信息

GET 请求URL： https://account.izhiju.cn/realms/zhiju/account

请求头参数： Content-Type: application/json Authorization: Bearer {{token}}

返回结果：

未授权，状态码401
```
{
"error": "HTTP 401 Unauthorized",
"error_description": "For more on this error consult the server log at the debug level."
}
```
1. 成功，状态码200, 返回如下内容： json { "id": "456637c0-c3a0-412a-8aeb-37f518ac11ed", "username": "alva", "firstName": "alva1", "lastName": "huang", "email": "alva@izhiju.cn", "emailVerified": false, "attributes": { "phoneNumber": [ "18680533727" ], "picture": [ "https://account.izhiju.cn/resources/2cyxv/account/keycloak.v3/logo.svg" ] } }

更新用户信息

POST 请求URL： https://account.izhiju.cn/realms/zhiju/account

请求头参数： Content-Type: application/json Authorization: Bearer {{token}}

{
  "id": "456637c0-c3a0-412a-8aeb-37f518ac11ed",
  "username": "alva",
  "firstName": "alva1",
  "lastName": "huang",
  "email": "alva@izhiju.cn",
  "emailVerified": false,
  "attributes": {
    "phoneNumber": [
      "18680533727"
    ],
    "picture": [
      "https://account.izhiju.cn/resources/2cyxv/account/keycloak.v3/logo.svg"
    ]
  }
}

返回结果：

未认证授权，状态码401, token错误或过期

{
"error": "HTTP 401 Unauthorized",
"error_description": "For more on this error consult the server log at the debug level."
}

更新成功，状态码204, 无内容返回

更新失败，状态码400，下面为用户名不可修改返回的错误信息

{
"errors": [
{
"field": "username",
"errorMessage": "error-user-attribute-read-only",
"params": [
"${username}"
]
},
{
"field": "username",
"errorMessage": "readOnlyUsernameMessage",
"params": [
"${username}"
]
}
]
}

发送短信验证码

POST 请求URL： https://account.izhiju.cn/realms/zhiju/sms/verification-code 请求头参数： Content-Type: application/x-www-form-urlencoded

请求体参数： | 参数名 | 参数类型 | 默认值 | 说明 | | ------------- | -------- | -------------- | --------------------------------------------- | | areaCode | string | 86 | 手机号所属的区号，默认86 | | phoneNumber | string | | 手机号，11位数字 |

正确状态码200,返回结果： { "expires_in": 1714988276153, "resend_expires": 1714988036153, "status": 1 }
错误返回结果： { "error": "sms_verification_code_error", "error_description": "sms verification code error" }

通过短信验证码修改手机号码

POST 请求URL：https://account.izhiju.cn/realms/zhiju/sms/update-profile

请求头参数： Authorization: Bearer {{token}} Content-Type: application/x-www-form-urlencoded 请求体参数： | 参数名 | 参数类型 | 默认值 | 说明 | | ------------- | -------- | -------------- | --------------------------------------------- | | areaCode | string | 86 | 手机号所属的区号，默认86 | | phoneNumber | string | | 手机号，11位数字 | | smsCode | string | | 短信验证码，6位数字 |

用户头像管理

头像配置 spi-avatar-provider-config-

参数名	参数类型	默认值	说明
defaultAvatar	`string`	`/`	URL for default avatar
alwaysRedirect	`boolean`	`false`	Should always redirect to static image url
defaultSize	`string`	`lg`	Default avatar size
storageService	`string`	`file`	Provider to store avatar files

头像存储配置 spi-avatar-storage-file-

| 参数名 | 参数类型 | 默认值 |说明 | | root | string |/ | FS storage root path | | route | string |/{realm}/avatar/{avatar_id}/avatar-{size}.png | URL and path to avatar file (Not need change) | | baseurl | string | /realms/| Keycloak base url | | default-avatar | string | /{realm}/avatar/default.png| Path to default avatar|

接口基本参数

| 参数名 | 参数类型 |默认值 | 说明 | | size | enum<String>("xs", "sm", "md", "lg", "xl", "xxl") | {Config.defaultSize} |Avatar file size | | format | enum<String>("raw", "json") |raw| Response format |

通过用户ID获取头像

Request:

GET /realms/{realm}/avatar/by-userid/{user_id}

没有size参数时，返回默认lg大头像，没有format参数时，默认format为raw，返回原始图片

请求参数中指定format参数为json时，返回json格式数据:

{
    status: 1,
    avatar: "", // avatar url for lg
    avatar_tpl: "", // avatar url template, placeholder: %s
}

通过用户名获取头像

Request:

GET /realms/{realm}/avatar/by-username/{username}

Respose (While format=json):

{
    status: 1,
    avatar: "", // avatar url for lg
    avatar_tpl: "", // avatar url template, placeholder: %s
}

获取默认头像

Request:

GET /realms/{realm}/avatar/default

Respose (While format=json):

{
    status: 1,
    avatar: "", // avatar url for lg
    avatar_tpl: "", // avatar url template, placeholder: %s
}

上传头像

Request:

POST /realms/{realm}/avatar

image=<image file>

account.md 13 KB История Исходник

前言

概述

范围说明

账户系统

HTTP返回状态码说明

用户登陆认证

微信用户注册登陆接口

客户端登陆认证接口

用户信息管理

获取用户信息

更新用户信息

发送短信验证码

通过短信验证码修改手机号码

用户头像管理

头像配置 spi-avatar-provider-config-

头像存储配置 spi-avatar-storage-file-

接口基本参数

通过用户ID获取头像

通过用户名获取头像

获取默认头像

上传头像

account.md 13 KB

История Исходник