入门指引¶

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

场景描述¶

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

任务描述¶

开始前准备¶

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

步骤1：创建API组¶

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

选择 API管理 > 我的API，点击 新建API组，填入以下配置信息：
- 服务实例：EnOS Partner共享实例
  
  备注
  
  EnOS OU用户可以选择EnOS Platform专享实例或EnOS Partner共享实例，默认EnOS Platform专享实例；三方OU用户默认仅可EnOS Partner共享实例。
- 分组名称：Wind-turbine-service
- 分组路径：/wind-turbine
- 分组描述：Wind turbine service
点击保存，完成API组的创建。

步骤2：创建API¶

点击已创建的API组Wind-turbine-service，在 基本信息 页，点击 添加API。
在 API基本信息 中，配置如下信息，然后点击 下一步：
- API名称：GetTurbineByCaseId
- API类型：三方。上一步服务实例已选择 EnOS Partner共享实例，此处API类型默认选择三方。
- 验证方式：无需验证
- API描述：GetTurbineByCaseId
在 API后端服务 中，配置如下信息，然后点击 下一步：
- 后端服务地址：https://eersc.usgs.gov
- HTTP Method：GET
- 后端请求路径：/api/uswtdb/v1/turbines
- 入参请求模式：透传
- 连接超时时间：3000
- 读取超时时间：60000
- 写入超时时间：60000

点击 添加请求参数，按照以下信息添加参数“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（选做）¶

点击GetTurbineByCaseId后的 API概览，进入API概览详情页，点击 基础信息 栏右上角的按钮对此API进行克隆。
依次按照需求修改克隆后的API基本信息、API后端服务、API请求、返回结果和插件配置。
点击完成，完成对GetTurbineByCaseId的克隆。

步骤4：调试API¶

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

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

步骤5：发布API¶

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

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

步骤6：调用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 快速入门。

步骤7：监控API¶

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

备注

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

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

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

步骤8：自定义验证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调用。