SQL模式

前提条件

在开始执行操作前，需满足以下条件：

• 基于服务单元生成API的场景中，需要完成服务单元的创建。具体操作，请参见创建元数据。

• 基于逻辑表生成API的场景中，需要完成逻辑表（维度逻辑表、事实逻辑表和汇总逻辑表）的创建。

  具体操作，请参见创建并配置普通维度逻辑表、创建并配置事实逻辑表、创建汇总逻辑表。

使用限制

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

注意事项

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

操作流程

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

   选择API的生成方式为自定义SQL模式。

2. 步骤二：配置API基础信息

   配置API的名称、请求方式、数据更新频率及协议。

3. 步骤三：配置API请求参数和返回参数

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

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

1. 在Dataphin首页，单击顶部菜单栏服务。

   系统默认进入市场页面。

2. 按照下图操作指引，进入新建API配置向导页面。

   

3. 在新建API配置向导页面，选择创建API的方式为SQL模式后，单击下一步。

   

步骤二：配置API基础信息

在API基础信息配置页面，配置API基本信息后，单击下一步。

步骤三：配置API请求参数和返回参数

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

1. 在参数配置页面，配置API的请求参数和返回参数从服务单元或Dataphin逻辑表中的取数逻辑。

   1. （可选）数据源类型支持服务单元或Dataphin逻辑表。

      选择了服务单元或Dataphin逻辑表后，页面下方会为您展示已选择的服务单元或Dataphin逻辑表中所有的字段，便于您编写API SQL时参考。

      服务单元

      

      Dataphin逻辑表

      

      参数	描述
      模式	支持Basic或Dev_Prod两种模式。 Basic模式下开发时、提交及发布线上均读取生产库。 Dev-Prod模式下开发及提交读取开发库，发布线上读取生产库。
      数据源类型	可选择服务单元或Dataphin逻辑表。 当数据源类型选择服务单元时，需选择服务单元。支持复制全表字段或单个字段。 当数据源类型选择Dataphin逻辑表时，需选择该逻辑表所在的业务板块及选中的板块下的逻辑表。

   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. 按照下图操作指引，试运行API SQL。

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

   4. 单击解析参数后，再配置请求参数和返回参数的基本信息。

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

      参数	描述
      参数名	对外开放的参数。
      绑定字段	对外不可见的参数，API调用时实际访问的参数。
      参数类型	参数类型包括Double、Float、String、Date、Boolean、Int、Long、Short、Byte、Bigdecimal、Binary。您需要选择参数名对应的绑定字段的参数类型。 如果逻辑表的字段类型不在待选参数类型范围内，推荐您选择String。
      示例	填写请求参数值和返回参数值的示例，便于开发者理解。
      是否必填	选择请求参数是否为调用API时的必填参数。 选择为否：调用API的语句中没有该参数也可以执行调用API的SQL语句。 选择为是：调用API的语句中没有该参数无法执行调用API的SQL语句。 例如，请求参数为id，请求参数为必填参数，返回参数为name；则执行以下语句会有不同的返回：
      描述	填写对请求参数和返回参数的简单描述。

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

   后续您需要将生成的API发布至数据服务市场中，应用才能调用该API。