连接 API

使用 API 的场景

很多时候我们会需要从 API 获取数据,卡拉云中内置了 API 的接口,你可以方便地在卡拉云中通过 API 接口,对数据进行增删改查。

通常来说,我们会在以下两种场景中使用到 API

第一种 连接内部的后端服务 API

很多时候,在公司的后端会有已经成型的业务 API。

比如说,如果运营需要经常按用户 ID 查询用户的详情,那么后端可能会有一个接口,专门用来查询用户。对于这样的后端服务,卡拉云可以很容易地与后端对接起来,对 API 进行操作。

第二种 连接第三方的 API

有时候,你的业务可能需要用到第三方的 API。

比如说你是美团,你的业务中需要查询订单用户的地址来确认当地的天气,以确定骑手延误是否是因为下雨导致。那么这时候,你就需要按地址来查询天气信息。这样的天气接口有很多可选的第三方服务,如果你需要连接第三方 API 并与内部数据串联起来,卡拉云可以帮你大显身手。

如何在卡拉云中连接 API

要在卡拉云的应用中连接 API 非常简单,你只需

  1. 添加一个 RESTFUL API 数据源
  2. 在应用中,添加查询对应数据源的查询

添加 API 数据源

要在卡拉云中添加一个数据源,只需要在主界面上,点击 数据源 按钮,即可以进入数据源页面。点击 添加数据源,按说明将需要的字段填入即可。

连接 API 数据源

在 1 中填入任意数据源名称,如 测试 API,在端点中填入 API 端点前缀

👍
什么是端点前缀
多数 RESTFUL API 的端点(end-point)设计是按照层级来设计的。比如说,https://api.your_api.com/users/ 和 https://api.your_api.com/orders/ 分别表示用户 API 和订单 API。如果你希望在查询时可以灵活地同时用到用户和订单的 api,则此处的端点前缀应该填入 https://api.your_api.com。这样,在应用内的查询中就可以比较方便地切换(详见下文)

如果你手上没有 API 也没有关系, 我们可以使用一个非常流行的测试 API 来说明如何连接。在本文中,我们用 jsonplaceholder 这个 API 服务,它事实上就是一个返回占位数据的 API。到它的官网你会看到有几个提前预定好的接口,直接在浏览器里粘贴对应的接口就会返回一些 JSON 数据

📘
JSONPlaceholder

JsonPlaceholder 是一个免费的第三方 API,它与使用其它任何 API 的流程一样,所以我们用这个服务来说明如何在卡拉云中连接 API。 在它的帮助页面它列出了一些端口,比如

GET https://jsonplaceholder.typicode.com/photos // 获取照片数据

GET https://jsonplaceholder.typicode.com/comments // 获取评论

GET https://jsonplaceholder.typicode.com/users // 获取用户

我们在上图的第 2 步中 API 端点 项内,填入前缀 https://jsonplaceholder.typicode.com/

查询 API

在上一节我们保存好数据源后,现在就可以在应用中针对 API 数据源来进行查询了。

首先我们新建一个应用

新建应用

新建应用后,点击编辑应用开始编辑,并编辑器在上方点击 查询编辑

新建查询

新建好查询后,我们在端点中填入 photos/1,请注意,因为我们在新建数据源时,以 / 结尾,也就是 https://jsonplaceholder.typicode.com/ 因此在这里填入端点后缀时,不需要额外的 / 前缀了。整个端点连起来就是 https://jsonplaceholder.typicode.com/photos/1

此时如下图,默认的 HTTP 方法是 GET,我们就可以尝试请求这个 GET HTTP 请求了。点保存查询,再点运行

尝试查询 API

🚧
每次编辑查询均需保存
在每次编辑完查询后,系统会提示你保存查询。只有保存后的查询才可以运行,否则系统会提示你查询错误。当出现保存提示时,请在编辑完后保存查询后再运行

这时,在下方的预览框里就出现了我们查询的数据,类似

[
  {
    "data": {
      "albumId": 1,
      "id": 1,
      "title": "accusamus beatae ad facilis cum similique qui sunt",
      "url": "https://via.placeholder.com/600/92c952",
      "thumbnailUrl": "https://via.placeholder.com/150/92c952"
    },
    "executionState": "SUCCESS",

.....以下省略

访问查询结果

当一个查询运行后,它获取的数据会存储在查询的 data 属性中,在应用的其它任意地方,你都可以引用查询的结果。比如如果查询名为 queryUser,那么查询出来的数据则为 queryUser.data。如果这个查询从来没有运行过,则数据为 null

我们用一个例子来说明。

回到界面编辑中,我们拖入一个图片组件,点击图片进行设置。在图片组件的 URL 属性中,我们引用刚才查询出来的数据中的 url 项,如下图

引用数据

当然,这里只是用一个简单的例子说明如何请求一个 GET HTTP 请求,同时请求的图片也只是占位图片。卡拉云支持所有 HTTP 请求类型(GET, POST, PUT, PATCH),你可以用卡拉云接入更多样的数据和任意 API 读写操作。

如何进行 API 鉴权

在很多时候,不管是内部 API 调用还是外部第三方 API,都会需要在 API 调用时,进行鉴权。

常见的鉴权方式有以下几种

  1. 将 token 包含在端点中
  2. 将 token 包含在请求头中
  3. 将帐号和密码包含在请求头中

不管是使用哪种鉴权方式,本质上都是在请求时将某种令牌发送给服务器。在卡拉云的 API 请求中,你可以指定请求头键值对, 这样你就可以将 token 或者其它令牌放到 Header 中,如下图所示

请示头设置

接下来做什么

到这里,你应该就可以熟练地在卡拉云中使用 API 查询了。下一步你可以深入学习查询的其它用法,包括用查询触发事件实现更新后组件自动刷新等功能。

同时,你也可以开始探索各种组件,搭建功能更丰富的后台系统应用。