知晓云 Web API

知晓云 Web API 可以让你用任何支持发送 HTTP 请求的设备来与知晓云进行交互,你可以使用 Web API 做很多事情,比如:

  • 用户注册,用户登录,密码找回
  • 给用户的手机号发送短信
  • 上传文件
  • 触发云函数
  • 对数据表进行增删改查

Web API 类别

如何构造 HTTP 请求

首先,发起一个 HTTP 请求时,你得知道服务器的域名

服务器域名

首先,发起一个 HTTP 请求时,要先获取应用的服务器域名

获取方式
  • 进入知晓云控制台设置页面, 在左上角选择你的应用client-id
  • 在选择完应用后(必须先选择应用,因为不同的应用会有不同的 服务器域名),向下滑动页面,在服务器域名中就可以找到 request 合法域名server-url
使用方式

Web API 形如 https://{{服务器域名}}/hserve/v2.0/idp/pay/order/

(eg: https://abcd11223344daeabcd.myminapp.com/hserve/v2.0/idp/pay/order/)

其中服务器域名 abcd11223344daeabcd.myminapp.com 就是你在上面获取到的 request 合法域名 的值

使用例子
  1. curl -X GET \
  2. -H "X-Hydrogen-Client-ID: a4d2d62965dda4d2d62965dd" \
  3. -H "Authorization: Hydrogen-r1 t3yzfew6tt3yzfew6t" \
  4. -H "Content-Type: application/json" \
  5. https://abcd11223344daeabcd.myminapp.com/hserve/v2.0/idp/pay/order/

知道服务器域名之后,你就可以利用 HTTP 请求和位于服务器上的应用交互了,但是服务器怎么辨别收到 HTTP 请求时是属于哪一个应用?这时候,就需要用到 ClientID

ClientID

区分应用的唯一凭证,服务器依靠这个字段来辨别请求者的应用

获取方式
  • 进入知晓云控制台设置页面, 在左上角选择你的应用client-id
  • 在选择完应用后(必须先选择应用,因为不同的应用会有不同的 ClientID),向下滑动页面,在开发者 ID中就可以找到 ClientIDclient-id-get
使用方式

在你请求的 HTTP-Header 里,加入以下的项:

X-Hydrogen-Client-ID: a4d2d62965dda4d2d62965dd

其中的 a4d2d62965dda4d2d62965dd 为你在控制台拿到的 ClientID

使用示例

获取应用的内容库分类列表

  1. curl -X GET \
  2. -H "X-Hydrogen-Client-ID: a4d2d62965dda4d2d62965dd" \
  3. -H "Content-Type: application/json" \
  4. https://abcd11223344daeabcd.myminapp.com/hserve/v1/content/category/?content_group_id=1

有一些 WEB API 除了需要知道 ClientID 外,还需要知道请求来自哪一名用户(如修改用户信息,应用就需要知道修改的是哪一个用户的信息),Access Token 能满足应用的这个需求

Access Token

用于应用中用户的鉴权

获取方式
  1. {
  2. "_email": "hgzchn@qq.com",
  3. "_email_verified": true,
  4. "_provider": {},
  5. "_session": {
  6. "ip_address": "14.17.111.222",
  7. "login_method": "email",
  8. "session_key": "t3yzfew6tt3yzfew6t",
  9. "user_agent": "blablabla"
  10. },
  11. "avatar": "https://blablabla.png",
  12. "created_at": 1554777211,
  13. "created_by": 34719381684550,
  14. "expires_in": 2592000,
  15. "id": 34719381600000,
  16. "is_authorized": false,
  17. "token": "t3yzfew6tt3yzfew6t", # 用户的 Access Token
  18. "updated_at": 1554777211,
  19. "user_id": 34719381600000
  20. }
使用方式

在你请求的 HTTP-Header 里,加入以下的项:

Authorization: Hydrogen-r1 t3yzfew6tt3yzfew6t

其中的 t3yzfew6tt3yzfew6t 为用户的Access Token

使用示例

用户登出(需同时提供 ClientID)

  1. curl -X POST \
  2. -H "X-Hydrogen-Client-ID: a4d2d62965dda4d2d62965dd" \
  3. -H "Authorization: Hydrogen-r1 t3yzfew6tt3yzfew6t" \
  4. -H "Content-Type: application/json" \
  5. https://abcd11223344daeabcd.myminapp.com/hserve/v2.0/session/destroy/

请求格式

对于 Web API 的请求,如果需要附带数据,请求的主体必须是 JSON 格式,而且 HTTP headerContent-Type 需要设置为 application/json

响应格式

参考错误响应