文档

通过直连数据源模式创建API

更新时间:

直连数据源模式是通过SQL直接从数据源创建API。本文为您介绍如何使用直连API模式生成API。

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

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

    系统默认进入市场页面。

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

    image..png

  3. API创建方式选择对话框,选择直连数据源模式后,单击确定

步骤二:配置API参数信息

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

    API基本信息配置

    image..png

    参数

    描述

    API名称

    填写API的名称。命名规则如下:

    • 只能包含汉字、字母、数字或下划线(_)。

    • 长度为4~42个字符。

    • 以字母开头。

    • 全局唯一。

    请求方式

    API请求方式包括GET和LIST:

    • GET:请求服务器获取指定的某个资源。

    • LIST:请求服务器获取某一部分的资源。

    API分组

    选择当前项目下配置的API分组,如需创建,请参见创建服务分组

    描述

    填写对API简单的描述。不超过128字符。

    协议

    默认选中HTTP。HTTP即超文本传输协议HTTP(HyperText Transfer Protocol),是应用最为广泛的网络协议。

    勾选HTTPS协议时,请确保独立域名的SSL证书有效,避免无法正常调用。请通过选择平台管理网络配置,在网络配置页面,进行SSL证书配置。

    超时时间

    超时时间用于监控API调用的时长。调用API过程中如果超过了设定的超时时间,则调用API时会报错,便于您及时发现并处理调用API的异常情况。异常情况查看,详情请参见查看及管理运维监控API

    最大返回条数

    API最大的返回条数。需输入1~10000的正整数。当请求方式选择为LIST时显示该配置项。

    缓存设置

    支持开启关闭。开启后需配置缓存时长

    版本号

    请填写API的版本号,每份配置信息会有所属版本号,以便于和上个版本信息对比。64字符以内。该API下版本号唯一。

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

    在配置API请求参数返回参数过程中,您需要先确定输入参数和输出参数的来源表,再编写API SQL并解析出请求参数和返回参数,最后配置请求参数和返回参数的基本信息。

    1. 参照以下图表,确定输入参数和输出参数的来源表,并根据参考示例编写API SQL脚本。

      image..png

      参数

      描述

      模式

      选择数据来源环境,支持BasicDev-Prod

      • Basic模式下开发时、提交及发布线上均读取生产库。

      • Dev-Prod模式下开发及提交读取开发库,发布线上读取生产库。

      数据源

      选择数据源类型及该类型的数据源。包含IMPALAOracleMySQLElasticsearchHbase0.9.4/1.1.x/2.xPostgreSQLMicrosoft SQL ServerHologresLindormClickHouseStarRocksTDengine

      说明

      MySQL支持版本5.x和8.x。

      SQL模式

      支持选择基础SQL高级SQL两种模式。

      • 基础SQL:通过基础SQL语法来编写查询逻辑。SQL逻辑示例请参见参考示例

      • 高级SQL:通过支持Mybatis标签的SQL语法来编写查询逻辑。目前支持的标签类型包括:if、choose、when、otherwise、trim、foreach和where。SQL逻辑示例请参见参考示例

      API SQL脚本编辑

      • 支持同一数据源下的单表查询、多表关联查询和嵌套查询。

      • PostgreSQL数据源类型不支持跨Schema。

      • 不支持以下用法:

        • 不支持多条SQL语句。

        • 不支持INSERT、UPDATE、CREATE和DELETE等非SELECT语法。

        • 不支持SELECT *,查询时必须明确指定查询的列。

        • 不支持在SQL语句里设置参数的可选项。

      • 如果SELECT查询列的列名带有表名前缀(例如t.name),则必须取别名作为返回参数名(例如t.name as name)。

      • 如果使用聚合函数(MIN、MAX、SUM和COUNT等),必须取别名作为返回参数名。例如sum(num) as total_num

      • 支持在SELECT区域配置参数,例如select id_card, sum(case when id_card like ${id_card} then 1 else 0 end) as proj_score from 数据表A where c like ${id_card} group by id_card

      • 不支持在SQL中使用分页语句,需通过分页参数实现分页。

      • 支持传参的方式动态指定SQL语句查询返回的字段,参数名必须以var_cols开头(格式:var_cols_xxx),并将参数写在查询语句内,调用API时,传入需要查询的字段即可。例如:

        • API的SQL语句:select id,${var_cols_args} from table1

        • var_cols_args参数传入值:name,age,old

        • API实际执行的SQL语句:select id,name,age,old from table1

      • 数据源类型为Elasticsearch时:

        • 当不指定scrollId时,最多只能查询前10000条数据,调用设置分页PageStart和PageSize时,注意不要查询超过10000条后的数据,否则调用会失败。

          例如:PageStart设置为9998,PageSize最大只能设置2。

        • 如果要查询10000条以后的数据,需要where语句指定scrollId,可以在API开发时指定一个请求参数scrollId,查询时传入对应的scrollId值。

          说明

          指定了scrollId值查询时,就不能使用分页,即PageStart和PageSize不能传值,否则调用失败。

        • 目前,只支持scrollId这个字段作为条件查询,其余字段不生效。例如:select a from table where scrollId=${scrollId}

      参考示例

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

      • 基础SQL示例

        • 模板一:

          select id_card,name 
          from 数据表A 
          where c=${id_card}
        • 模板二:

          select id_card,name
          from 数据表A 
          where c in (${id_card})
        • 模板三:

          select max(a) as c,sum(a) as b ,min(a) as d,count(*) as e 
          from 数据表A 
          where c like ${id_card}
        • 模板四:

          select t.name as name 
          from 数据表A 
          c=${id_card}
        • 模板五:

          select (a+b) as acd,(b+c) as bcf 
          from 数据表A 
          where c=${id_card} and/or b>=${num} and/or c<=${num1}
        • 模板六:

          select id_card, sum(case when name like ${name} then 1 else 0 end) as proj_score 
          from 数据表A 
          where c=${id_card} group by id_card
      • 高级SQL示例

        • 示例一:

          select id from 数据表
           <where>
           <if test="name != null ">
           AND age &gt; ${age}
           </if>
           <if test="name == null">
           AND age &lt; ${age}
           </if>
           </where>
        • 示例二:

          select id from 数据表
           <where>
           <if test="name != null ">
           AND age > #{age}
           </if>
           <if test="name == null">
           AND age &lt; #{age}
           </if>
           </where>

      格式化

      支持对SQL语句格式化处理展示,仅支持对基础SQL。

      数据表

      选择数据源中的数据表。选择后,会在字段信息区域,展示已选择数据表中的所有字段。支持复制字段名称及支持复制全表字段或单个字段。

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

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

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

        image..png

    3. 单击SQL编译后(若选择基础SQL,则点击解析参数),配置请求参数返回参数的基本信息。

      单击SQL编译后,Dataphin会自动解析出API SQL的入参和出参并分别添加至请求参数返回参数区域。请求参数和返回参数的基本信息基本一致,下表介绍请求参数和返回参数的基本信息说明。

      image..png

      参数

      描述

      参数名

      显示对外开放的参数名。

      参数类型

      参数类型包括DOUBLEFlOATSTRINGDATE(yyyy-MM-dd HH:mm:ss)BOOLEANINTLONGSHORTBYTEBIGDECIMALBINARY,需选择参数名对应的绑定字段的参数类型。

      如果逻辑表的字段类型不在待选参数类型范围内,推荐选择String。

      操作符

      选择您所需的操作符。

      说明

      expr代表高级SQL中标签参数表达式。

      示例

      填写请求参数值和返回参数值的示例,便于开发者理解。

      描述

      填写对请求参数和返回参数的简单描述。

      是否必填

      选择请求参数是否为调用API时的必填参数。

      • 选择为:调用API的语句中没有该参数也可以执行调用API的SQL语句。

      • 选择为:调用API的语句中没有该参数无法执行调用API的SQL语句。

      例如,请求参数为id,请求参数为必填参数,返回参数为name;则执行以下语句会有不同的返回:

      • 返回对应的name字段及数据:seclect name from tableA where id=5;

      • SQL语句执行报错:seclect name from tableA;

      说明

      高级SQL语句较为复杂,SQL编译解析的参数不一定完整且正确。因此,您可根据SQL语句对解析结果进行删除参数、新增请求参数和新增返回参数操作。

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

后续步骤

  • 生成API后,需要对API进行测试并发布至数据服务市场,便于后续应用可以调用API。具体操作,请参见测试与发布API

  • 若需要对API进行删除、版本管理、转让负责人等操作,请参见查看及管理API

  • 本页导读 (0)
文档反馈