# 开发API
本章节介绍如何通过数据服务创建、测试、发布查询英语考试信息的API。
#### 新建API
1. [登录DataArts Studio管理控制台](https://console.huaweicloud.com/dayu/)。
   
   详情请参考[访问DataArts Studio实例控制台](https://support.huaweicloud.com/usermanual-dataartsstudio/dataartsstudio_01_0001.html)。
   
   
2. 在DataArts Studio控制台首页，选择对应工作空间的"数据服务"模块，进入数据服务页面。
3. 在左侧导航栏选择服务版本（例如：专享版），进入总览页。
4. 通过以下任意一种方法，新建API。 
   - 单击左侧导航树中的"API目录"，再单击"新建API"。
   
   - 单击左侧导航树中的"API管理"，再单击"新建"。
   
   
   
   
5. 在新建API基本配置页面，填写基本信息。重要参数介绍如下： 
   - **API名称** ：支持中文、英文、数字、下划线，且只能以英文或中文开头，3-64个字符。
     本示例以TestScore为例。
     
   
   - **请求Path** ：指定API访问路径，请求Path即完整的URL中，域名之后、查询参数之前的部分。
     本示例以/TestScore为例。
     
   
   - **参数协议** ：用于传输请求的协议，专享版支持HTTPS协议。
     本示例以HTTPS为例。
     
   
   - **请求方式** ：表示请求什么类型的操作，包含GET、POST等，遵循RESTful风格。
     本示例以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基本配置   
     ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002494976272.png "点击放大")
     
     
   
   
   
   
6. 单击"下一步"进入"取数逻辑"页面，配置取数方式，配置数据连接，设置参数信息。 
   1. **配置取数方式**
      取数方式支持"配置方式"、"脚本方式"和"MyBatis方式"。
      - 配置方式：使用配置方式生成数据API简单且容易上手，用户不需编写任何代码，通过产品界面进行勾选配置即可快速生成API。推荐对API功能的要求不高或者无代码开发经验的用户使用。
      
      - 脚本方式/MyBatis方式：可以满足高阶用户的个性化查询需求，允许用户自行编写API的查询SQL，并支持多表关联、复杂查询条件以及聚合函数等能力。请详见[脚本/MyBatis方式生成API](https://support.huaweicloud.com/usermanual-dataartsstudio/dataartsstudio_01_0306.html)。
       
      本示例以"配置方式"为例。
      
   
   2. **配置数据连接**
      配置数据源类型、数据连接、数据库和数据表。
      本示例选择HIVE数据源类型，选择在管理中心创建的MRS Hive连接，选择前面准备的数据库和数据表。
      图2配置连接参数   
      ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002527065651.png "点击放大")
      
      
   
   3. **配置参数字段**
      单击"参数设置"后的"添加"，添加参数页面自动列出这个表的所有字段，分别勾选需要设置为请求参数、返回参数和排序参数的字段，分别添加到请求参数、返回参数和排序参数列表当中。
      本示例中期望查询特定考生的成绩和考生是否通过考试，"请求参数"勾选准考证号Number字段和考试成绩Score字段，"返回参数"可以勾选所有字段，期望对通过考试的考生名单按成绩高低进行排序，"排序参数"勾选Score字段。
      图3添加参数   
      ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002501691170.png "点击放大")
      
      
   
   4. **编辑请求参数信息**
      请求参数主要分为三部分，绑定参数、绑定字段、操作符。在请求参数列表中，需要设置绑定参数和操作符。
      - 绑定参数对外开放，选择为基本配置中定义的入参，是用户访问API时直接使用的参数。
      
      - 绑定字段对外不可见，是所选的数据表中的字段，为API调用时实际访问的内容。
      
      - 操作符则是用户访问API时，对绑定字段和绑定参数的处理方式。当前支持的操作符及含义请参见[表2](https://support.huaweicloud.com/usermanual-dataartsstudio/dataartsstudio_01_0305.html#dataartsstudio_01_0305__table3361128679)。
       
      本示例中，"绑定参数"分别选择Score和Number。Score参数绑定表中的Score字段，期望查询考生是否通过考试，操作符选择"\>="。Number参数绑定表中的Number字段，期望查询特定考生的成绩，操作符选择"="。
      图4参数设置   
      ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002495039380.png "点击放大")
      
      
   
   5. **编辑返回参数信息**
      返回参数主要分为三部分，参数名、绑定字段、参数类型。
      - 参数名对外开放，可自定义，是API返回时最终展示给用户的参数名称。
      
      - 绑定字段对外不可见，是所选的数据表中的字段，是API调用时实际返回的内容。
      
      - 参数类型则是API调用时，数据的呈现格式，分为数值型和字符型两类。
      
      
      本示例中Score参数是数值类型，参数类型选择NUMBER，其他参数类型保持STRING不变。
      图5返回参数   
      ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002533778369.png "点击放大")
      
      
   
   6. **编辑排序参数信息。**
      排序参数主要分为四部分，参数名、字段名称、是否可选以及排序方式，支持多个排序参数。
      - 参数名可自定义，用于与字段名称关联。
      
      - 字段名称对外不可见，是所选的数据表中的字段，是API调用时实际访问的内容。
      
      - 是否可选决定了调用API时此排序参数是否必选。
      
      - 排序方式表示了当前参数允许使用的排序形式，分为升序、降序以及自定义。
      
      - 多个排序参数时，表示当第一个排序参数相等时，再逐一用后续排序参数去排序。
      
      
      本示例中，期望对通过考试的考生名单按成绩高低进行排序，设置排序参数是score，"排序方式"选择"降序"，并勾选"是否可选"。
      图6排序参数   
      ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002533611321.png "点击放大")
      
      
   
   7. **（可选）配置返回总条数。**
      专享版数据服务支持返回总条数，开启后可返回取值脚本执行结果数据的总条数。
      本示例不配置返回总条数，开关保持关闭。
      
   
   
   
   
7. 单击"下一步"，进入API测试页面。
 
#### 测试和发布API
1. 设置参数配置。 
   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设置参数配置   
      ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002497911972.png "点击放大")
      
      
   
   
   
   
2. 设置集群配置。 
   在集群列表中，选择准备工作中准备的集群，然后单击"连通性测试"，系统提示连通成功，说明该集群可用。如果没有准备集群，请参考[管理专享版集群](https://support.huaweicloud.com/usermanual-dataartsstudio/dataartsstudio_01_0314.html)章节，准备集群。
   如果您选择的是公共集群，可跳过此步操作。
   
   
3. 单击"开始测试"，如果在页面右侧的响应中返回"200 Success"说明测试成功，查看返回结果是否正确。 
   - 查询所有考生英语考试成绩：返回第1页中的前100条考生名单。
   
   - 查询特定考生的英语考试成绩：返回该考生的考试成绩和个人信息。
   
   - 查询特定考生是否通过英语考试：返回值为空，说明该考生未通过英语考试；返回值为考生的考试成绩和个人信息，说明该考试通过了英语考试。
   
   - 查询通过英语考试的考生名单：返回第1页中的前100条通过英语考试的考生名单。
   
   - 对通过英语考试的考生名单按成绩高低进行排序：从高到低返回前100条通过英语考试的考生名单。
   
   
   图8测试接口   
   ![](https://support.huaweicloud.com/usermanual-dataartsstudio/zh-cn_image_0000002535694445.png "点击放大")
   
   
   
4. 测试成功后，单击"发布"，提交该API的审核。 
   - 如果您只是开发者，请联系审核人员审核API，等待审核通过。审核通过后，API即创建成功。
   
   - 如果您既是开发者又是审核人，则跳过审核API操作。
     ![](https://support.huaweicloud.com/usermanual-dataartsstudio/public_sys-resources/note_3.0-zh-cn.png)
     在发布API时，会触发审核，审核机制如下：
     - 当发布人不具备审核人权限时，发布API时需要提交给审核人审核。
     
     - 当发布人具备审核人权限时，可无需审批直接发布API。
      
     - 如果您不是开发者，只是审核人，请前往"审核中心"审核API申请。