入门指引¶

本教程将指导你如何通过API管理快速创建、部署API，及将API发布给消费者调用。

场景描述¶

在API管理中创建、部署并发布名为GetTurbineByCaseId的接口。
以第三方身份调用该接口。

任务描述¶

开始前准备¶

拥有一个EnOS账号，并拥有定义API操作需要的相应权限，参考策略，角色，与权限。

步骤1：创建API组¶

创建API前需要先创建API组。API分组名称与分组路径全局唯一。

选择 API管理 > 我的API，点击 新建API组，填入以下配置信息：
- 分组名称：Wind-turbine-service
- 分组路径：/wind-turbine
- 分组描述：Wind turbine service
点击保存，完成API组的创建。

步骤2：创建API¶

点击已创建的API组Wind-turbine-service，在 基本信息 页，点击 添加API。
在 API基本信息 中，配置如下信息，然后点击 下一步：
- API名称：GetTurbineByCaseId
- API类型：三方
- 验证方式：无需验证
- API描述：GetTurbineByCaseId
在 API后端服务 中，配置如下信息，然后点击 下一步：
- 后端服务地址：https://eersc.usgs.gov
- HTTP Method：GET
- 后端请求路径：/api/uswtdb/v1/turbines
- 入参请求模式：透传
- 后端超时时间：3000
- 返回体是否包含文件：不包含
点击 添加请求参数，按照以下信息添加参数“caseid”，然后点击 下一步：
在 API请求 中，配置如下信息，然后点击点击 下一步：
- API版本：v1
- 请求路径：/turbines

在 返回结果 中，按照以下信息配置 成功结果示例 与 失败结果示例，然后点击 下一步：

成功结果示例：

{
 "case_id":3000783,
 "faa_ors":null,
 "faa_asn":null,
 "usgs_pr_id":15020,
 "t_state":"CA",
 "t_county":"Riverside County",
 "t_fips":"6065",
 "p_name":"unknown San Gorgonio Pass 4",
 "p_year":1985,
 "p_tnum":37,
 "p_cap":null,
 "t_manu":null,
 "t_model":null,
 "t_cap":null,
 "t_hh":null,
 "t_rd":null,
 "t_rsa":null,
 "t_ttlh":null,
 "t_conf_atr":1,
 "t_conf_loc":3,
 "t_img_date":"11/3/2018",
 "t_img_srce":"Digital Globe",
 "xlong":-116.62079,
 "ylat":33.94149
}

失败结果示例

{
  "details": "unexpected \"1\" expecting \"not\" or operator (eq, gt, ...)",
  "message": "\"failed to parse filter (1)\" (line 1, column 1)"
}

在 插件配置 中，点击“+”为API添加限流插件 Rate Limiting，次数限制配置为：2/分钟。
点击完成。
弹窗提示API GetTurbineByCaseId保存成功，可直接点击 发布API，也可点击确定，稍后可在 API列表 中将API状态设置为发布。

步骤3：调试API¶

在完成API创建后，需在 API列表 中将API状态设置为发布才能进行调试。

点击GetTurbineByCaseId操作栏中的 测试API。
将“3000783”作为 caseid 的值，点击 提交测试。
点击提交测试，在右侧查看真实请求URL和响应结果。
多次点击 提交测试。第三次点击后即可观察到已触发API限流。
返回至 API列表，将该API状态修改为下线，点击操作中的 API概览，修改插件 Rate Limiting 的次数限制为“2000/分钟”。

步骤4：发布API¶

对于新创建的第三方API，默认的公开状态为“私有”，需要在EnOS发布，并公开，才能被第三方调用。

在 API列表 中将GetTurbineByCaseId状态设置为发布，将 是否公开 设置为公开。
进入 公开API 即可看到API组 Wind-turbine-service。点击展开组即可查看GetTurbineByCaseId接口的详情。

步骤5：调用API¶

当完成API发布后，第三方用户就可以调用该API了。

public class test {
  public static void main (String[] args) {
    String appKey = "yourAccessKey";
    String appSecret = "yourSecretKey";
    String result =
            Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey).debug())
                .url(
                  "https://ag-cn5.envisioniot.com/wind-turbine-service/v1/turbines?&case_id=eq.3000783")
                .method("GET")
                .sync();

    }
}

有关如何调用API，可参考EnOS API 快速入门。

步骤6：监控API¶

API在被用户使用后即可以在 API监控 中查看API被调用的状况。

备注

使用 测试API 调用的次数与状态不会被计算在内。

点击统计可以查看近一小时、近一天、近一周该API被请求的次数与调用时延。

点击 健康度 可以查看该API在当日（24小时）内被调用的次数及调用成功率。

步骤7：自定义验证API¶

对于新发布的第三方API，在 自定义验证 中，通过将自定义验证和API绑定，可在API调用时，API管理执行自定义的验证逻辑。

选择 API管理 > 自定义验证，点击 创建自定义验证，在弹框中配置如下信息，点击保存；

验证名称：wind-turbine
添加自定义参数：
- 变量名：url
- 变量值：http://apim-api-test.beta-k8s-cn4.eniot.io/test/get/1/

验证脚本：

-- url 可以通过自定义变量赋值
-- apim_http_util 内置变量,http请求工具
-- cjson 内置变量,json解析工具
-- 返回两个值
-- 第一个返回值 true表示通过认证, 其它表示未通过
-- 第二个返回值 参考值 可以将响应的信息返回
-- -----------------------------------
function processLogic(api_queries, api_headers)
    local method = 'GET'
    local header = {}
    local body = {}
    url = url .. api_headers['caseid']
    local res = apim_http_util.do_http(url, method, header, body)
    if not (res.status == 200) then
        return false, res:read_body()
    end

    local resp_body = res:read_body()
    local response = cjson.decode(resp_body)

    -- 处理逻辑
    return response.value == 'test-1-version13000783', resp_body
end

点击验证名称为 wind-turbine 后的 绑定API 按钮，在弹框中搜索API分组 Wind-Turbine-Service-Demo，选择API GetTurbineByCaseId，点击保存。
参见步骤3 。在 API列表 中，点击GetTurbineByCaseId操作栏中的 测试API，在API调试栏输入有效Access Key和Secret Key，将“3000783”作为 caseid 的值，点击 提交测试。

备注

当API已被授权或已公开时，API调试将包含应用身份认证逻辑。调试时，请输入有效的Access Key、Secret Key，以便成功执行API调用。