开发API

• 单击左侧导航树中的“API目录”，再单击“新建API”。
• 单击左侧导航树中的“API管理”，再单击“新建”。

• API名称：支持中文、英文、数字、下划线，且只能以英文或中文开头，3-64个字符。

  本示例以TestScore为例。

• 请求Path：指定API访问路径，请求Path即完整的URL中，域名之后、查询参数之前的部分。

  本示例以/TestScore为例。

• 参数协议：用于传输请求的协议，共享版支持HTTP或HTTPS协议，专享版支持HTTPS协议。推荐选择HTTPS协议，HTTP安全性欠佳，可能会存在安全风险。

  本示例以HTTPS为例。

• 请求方式：表示请求什么类型的操作，包含GET、POST等，遵循resultful风格。

  本示例以GET为例。

• 安全认证：创建API时，支持选择APP认证、IAM认证和无认证几种认证方式。这些方式的区别在于认证方式和调用方法不同，推荐使用安全性更高的APP认证。

  本示例以APP认证为例。

• 入参定义：配置调用API需要输入的参数，此处定义后即为配置取数逻辑时的请求参数。入参定义主要由参数位置、参数类型、是否必填、允许空值以及默认值等组成。

  本示例中，期望查询特定考生的成绩和考生是否通过考试，所以需要传入考生的准考证号和通过考试的分数线，因此需要配置两个入参：准考证号Number、考试成绩Score。

  分别配置两个入参Number和Score。

  1. 单击“添加”，参数名配置为Number、Score。
  2. 参数位置均选择Query。
  3. Number参数类型需要设置为String，Score参数类型设置为Number。
  4. 考虑到API查询能力的扩展性，是否必填均选择非必填。
  5. 默认值均不设置，其他参数保持默认，无需填写。
  图1 基本配置
  

1. 配置取数方式
   取数方式支持“配置方式”、“脚本方式”和“MyBatis方式”。

   • 配置方式：使用配置方式生成数据API简单且容易上手，用户不需编写任何代码，通过产品界面进行勾选配置即可快速生成API。推荐对API功能的要求不高或者无代码开发经验的用户使用。
   • 脚本方式/MyBatis方式：可以满足高阶用户的个性化查询需求，允许用户自行编写API的查询SQL，并支持多表关联、复杂查询条件以及聚合函数等能力。请详见脚本/MyBatis方式生成API。

   本示例以“配置方式”为例。

2. 配置数据连接

   配置数据源类型、数据连接、数据库和数据表。

   本示例选择HIVE数据源类型，选择在管理中心创建的MRS Hive连接，选择前面准备的数据库和数据表。

   图2 配置连接参数
   

3. 配置参数字段

   单击“参数设置”后的“添加”，添加参数页面自动列出这个表的所有字段，分别勾选需要设置为请求参数、返回参数和排序参数的字段，分别添加到请求参数、返回参数和排序参数列表当中。

   本示例中期望查询特定考生的成绩和考生是否通过考试，“请求参数”勾选准考证号Number字段和考试成绩Score字段，“返回参数”可以勾选所有字段，期望对通过考试的考生名单按成绩高低进行排序，“排序参数”勾选Score字段。

   图3 添加参数
   

4. 编辑请求参数信息
   请求参数主要分为三部分，绑定参数、绑定字段、操作符。在请求参数列表中，需要设置绑定参数和操作符。

   • 绑定参数对外开放，选择为基本配置中定义的入参，是用户访问API时直接使用的参数。
   • 绑定字段对外不可见，是所选的数据表中的字段，为API调用时实际访问的内容。
   • 操作符则是用户访问API时，对绑定字段和绑定参数的处理方式。当前支持的操作符及含义请参见表2。
   本示例中，“绑定参数”分别选择Score和Number。Score参数绑定表中的Score字段，期望查询考生是否通过考试，操作符选择“>=”。Number参数绑定表中的Number字段，期望查询特定考生的成绩，操作符选择“=”。

   图4 参数设置
   

5. 编辑返回参数信息

   返回参数主要分为三部分，参数名、绑定字段、参数类型。

   • 参数名对外开放，可自定义，是API返回时最终展示给用户的参数名称。
   • 绑定字段对外不可见，是所选的数据表中的字段，是API调用时实际返回的内容。
   • 参数类型则是API调用时，数据的呈现格式，分为数值型和字符型两类。
   本示例中Score参数是数值类型，参数类型选择NUMBER，其他参数类型保持STRING不变。

   图5 返回参数
   

6. 编辑排序参数信息。

   排序参数主要分为四部分，参数名、字段名称、是否可选以及排序方式，支持多个排序参数。

   • 参数名可自定义，用于与字段名称关联。
   • 字段名称对外不可见，是所选的数据表中的字段，是API调用时实际访问的内容。
   • 是否可选决定了调用API时此排序参数是否必选。
   • 排序方式表示了当前参数允许使用的排序形式，分为升序、降序以及自定义。
   • 多个排序参数时，表示当第一个排序参数相等时，再逐一用后续排序参数去排序。

   本示例中，期望对通过考试的考生名单按成绩高低进行排序，设置排序参数是score，“排序方式”选择“降序”，并勾选“是否可选”。

   图6 排序参数
   

7. （可选）配置返回总条数。

   专享版数据服务支持返回总条数，开启后可返回取值脚本执行结果数据的总条数。

   本示例不配置返回总条数，开关保持关闭。

1. 填写入参取值，调整排序参数描述pre_order_by的值。

   本示例，可参考如下配置测试API：

   • 查询所有考生英语考试成绩：无需配置参数。
   • 查询特定考生的成绩：勾选Number参数后“是否传值”复选框，输入一个数据表中实际存在的准考证号。
   • 查询特定考生是否通过英语考试：勾选Number参数后“是否传值”复选框，输入一个数据表中实际存在的准考证号，勾选Score参数后“是否传值”复选框，Score参数值输入通过考试的分数线，以425为例。
   • 查询通过英语考试的考生名单：勾选Score参数后“是否传值”复选框，Score参数值输入通过考试的分数线，以425为例。
   • 对通过英语考试的考生名单按成绩高低进行排序：勾选Score参数后“是否传值”复选框，Score参数值输入通过考试的分数线，以425为例，勾选pre_order_by参数后“是否传值”复选框，值保持默认降序。
2. （可选）调整分页参数值。

   系统会对返回数据进行分页，API调试时默认按100的大小分页，返回第1页数据。

   本示例保持默认，返回数据表中第1页中的100条数据。

   图7 设置参数配置
   

在集群列表中，选择准备工作中准备的集群，然后单击“连通性测试”，系统提示连通成功，说明该集群可用。如果没有准备集群，请参考管理专享版集群章节，准备集群。

如果您选择的是公共集群，可跳过此步操作。

• 查询所有考生英语考试成绩：返回第1页中的前100条考生名单。
• 查询特定考生的英语考试成绩：返回该考生的考试成绩和个人信息。
• 查询特定考生是否通过英语考试：返回值为空，说明该考生未通过英语考试；返回值为考试的考试成绩和个人信息，说明该考试通过了英语考试。
• 查询通过英语考试的考生名单：返回第1页中的前100条通过英语考试的考生名单。
• 对通过英语考试的考生名单按成绩高低进行排序：从高到低返回前100条通过英语考试的考生名单。

图8 测试接口

• 如果您只是开发者，请联系审核人员审核API，等待审核通过。审核通过后，API即创建成功。
• 如果您既是开发者又是审核人，则跳过审核API操作。
  

  在发布API时，会触发审核，审核机制如下：

  • 当发布人不具备审核人权限时，发布API时需要提交给审核人审核。
  • 当发布人具备审核人权限时，可无需审批直接发布API。
  • 如果您不是开发者，只是审核人，请前往“审核中心”审核API申请。