知晓云 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中就可以找到 ClientID client-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

用于应用中用户的鉴权

获取方式
  • 请求用户注册或用户登录接口
  • 接口响应体的BODY中的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 header 的 Content-Type 需要设置为 application/json。

响应格式

参考错误响应