通过SQL模式创建API（服务单元）

前提条件

基于服务单元生成API，需先完成服务单元的创建。具体操作，请参见创建服务单元。

使用限制

支持服务项目管理员和开发用户角色的账号生成API。

注意事项

API的请求参数和返回参数需从同一个服务单元（单物理表服务单元或多物理表服务单元）中获取，否则后续无法正常调用该API。

步骤一：选择生成API的方式

1. 在Dataphin首页，单击顶部菜单栏服务。系统默认进入市场页面。

2. 按照下图操作指引，进入API创建方式选择对话框。

   

3. 在API创建方式选择对话框，选择逻辑表API-SQL模式（服务单元）后，单击确定。

步骤二：配置API参数信息

1. 在新建API页面，配置API基本信息和参数配置。

   API基本信息配置

   

   参数	描述
   API名称	填写API的名称。命名规则如下： 只能包含汉字、字母、数字或下划线（_）。 长度为4~42个字符。 以字母开头。 全局唯一。
   请求方式	API请求方式包括GET和LIST： GET：请求服务器获取指定的某个资源。 LIST：请求服务器获取某一部分的资源。
   数据更新频率	定义API返回数据的更新频率，选择每天、每小时或每分钟更新API返回的数据。
   API分组	选择当前项目下配置的API分组，如需创建，请参见创建服务分组。
   描述	填写对API简单的描述。不超过128字符。
   协议	默认选中HTTP。HTTP即超文本传输协议HTTP（HyperText Transfer Protocol），是应用最为广泛的网络协议。 勾选HTTPS协议时，请确保独立域名的SSL证书有效，避免无法正常调用。请通过选择平台管理网络配置，在网络配置页面，进行SSL证书配置。
   超时时间	超时时间用于监控API调用的时长。调用API过程中如果超过了设定的超时时间，则调用API时会报错，便于您及时发现并处理调用API的异常情况。异常情况查看，详情请参见运维监控概述。
   缓存设置	支持开启或关闭。开启后需配置缓存时长。
   版本号	请填写API的版本号，每份配置信息会有所属版本号，以便于和上个版本信息对比。64字符以内。该API下版本号唯一。

   API请求参数和返回参数配置

   在配置API请求参数和返回参数过程中，您需要先确定入参和出参的来源（服务单元），再编写API SQL并解析出请求参数和返回参数，最后配置请求参数和返回参数的基本信息。

   1. 在参数配置页面，选择了模式和服务单元后，页面下方会为您展示已选择的服务单元中所有的字段，便于您编写API SQL时参考。

      

      参数	描述
      模式	支持Basic或Dev_Prod两种模式。 Basic模式下开发时、提交及发布线上均读取生产库。 Dev-Prod模式下开发及提交读取开发库，发布线上读取生产库。
      服务单元对应字段	支持复制全表字段或单个字段。

   2. 您可根据参考示例编写API SQL。

      

      Dataphin能解析出返回参数和请求参数的SQL脚本模板如下：

      • 模板一：仅查询和返回服务单元中的字段。

        • 命令格式

          select <返回参数> from <服务单元名> where <请求参数>=${请求参数值}

        • 使用示例

          --在服务单元A中查询当c=id_card时，返回id_card和name。
          select id_card,name from 服务单元A where c=${id_card} 

      • 模板二：查询和返回服务单元包含的字段。

        • 命令格式

          select <返回参数> from <服务单元名> where <请求参数> in (${请求参数值})

        • 使用示例

          --在服务单元A中查询当c %in% id_card时，返回id_card和name。
          select id_card,name from 服务单元A where c in (${id_card})

      • 模板三：字段间支持使用max、sum、min和count聚合函数，同时支持使用like进行模糊匹配。

        • 命令格式

          select max(<返回参数1>) as <别名c>,sum(<返回参数1>) as <别名b> ,min(<返回参数1>) as <别名d>,count(*) as <别名e> from <服务单元A> where <请求参数名1> like ${请求参数值1}

        • 使用示例

          --在服务单元A中查询字段c %like% id_card时，返回字段a的最大值，参数名为c；返回a的最小值，参数名为d；返回a的总和，参数名为b。
          select max(a) as c,sum(a) as b ,min(a) as d,count(*) as e from 服务单元A where c like ${id_card}

      • 模板四：字段间的运算支持+（加法）、-（减法）、 * （乘法）、/（除法）、% （求余数）、 // （整除） **（幂次方），同时支持逻辑运算符and（与）和or（或）。

        • 命令格式

          select (<返回参数1>+<返回参数2>) as <别名>，(<返回参数2>+<返回参数3>) as <别名> from <服务单元A> where <字段c>=${请求参数名1} and <字段b>>=${请求参数名2} or <字段c><=${请求参数名3}

        • 使用示例

          --在服务单元A中查询当字段c=id_card，或字段b>=num，且字段c<=num1时，返回a+b、b+c的参数值，参数名分别为acd、bcf。
          select (a+b) as acd, (b+c) as bcf from 服务单元A where c=${id_card} aor b>=${num} or c<=${num1}

      重要

      上述四种模板中API的请求参数和返回参数需从同一个服务单元（单物理表服务单元或多物理表服务单元）中获取，否则后续无法正常调用该API。

   3. 单击SQL试运行，在请求参数输入对话框中，选择参数类型、操作符和试运行输入值，单击确认。

      • 运行日志：支持查看SQL试运行实际执行的SQL语句。

      • 试运行输入值需要配置成绑定字段的字段值，可以在数据预览页面选择绑定字段的字段值。

        

   4. 单击解析参数后，Dataphin会自动解析出API SQL的入参和出参并分别添加至请求参数和返回参数区域。请求参数和返回参数的基本信息基本一致，下表为您介绍请求参数和返回参数的基本信息及需要您配置的信息。

      

      参数	描述
      参数名	对外开放的参数。
      绑定字段	对外不可见的参数，API调用时实际访问的参数。
      参数类型	参数类型包括Double、Float、String、Date、Boolean、Int、Long、Short、Byte、Bigdecimal、Binary。您需要选择参数名对应的绑定字段的参数类型。 服务单元字段类型与请求参数字段类型保持一致，您选择对应的字段类型即可。
      示例	填写请求参数值和返回参数值的示例，便于开发者理解。
      是否必填	选择请求参数是否为调用API时的必填参数。 选择为否：调用API的语句中没有该参数也可以执行调用API的SQL语句。 选择为是：调用API的语句中没有该参数无法执行调用API的SQL语句。 例如，请求参数为id，请求参数为必填参数，返回参数为name；则执行以下语句会有不同的返回： seclect name from tableA where id=5；：则返回对应的name字段及数据结果。 seclect name from tableA;：则SQL语句执行报错。
      描述	填写对请求参数和返回参数的简单描述。

2. 单击提交，即可完成API的生成。