首页 智能数据建设与治理 Dataphin 数据服务 服务开发 创建API 直连数据源模式

直连数据源模式

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

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

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

    系统默认进入市场页面。

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

    image

  3. 在新建API配置向导页面，选择创建API的方式为直连数据源模式，单击下一步。

    image

步骤二：配置API基础信息

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

参数

描述

API名称

命名规则如下：

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

  • 长度为4~42个字符。

  • 以字母开头。

  • 全局唯一。

请求方式

API请求方式包括GET和LIST：

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

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

描述

填写对API简单的描述。

协议

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

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

超时时间

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

最大返回条数

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

缓存设置

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

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

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

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

    image

    参数

    描述

    模式

    选择数据来源环境，支持Basic或Dev-Prod。

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

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

    数据源类型

    选择数据源类型。包含IMPALA、Oracle、MySQL、PostgreSQL、Microsoft SQL Server和Hologres。

    说明

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

    数据源

    选择对应数据源类型的数据源。

    SQL模式

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

    • 基础SQL：支持格式化SQL语句。

    • 高级SQL：支持的标签类型包括：if、choose、when、otherwise、trim、foreach和where。

    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中使用分页语句，需通过分页参数实现分页。

    数据表

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

    参考示例

    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语句。

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

      image

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

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

    image

    参数

    描述

    参数名

    显示对外开放的参数名。

    参数类型

    参数类型包括DOUBLE、FlOAT、STRING、DATE(yyyy-MM-dd HH:mm:ss)、BOOLEAN、INT、LONG、SHORT、BYTE、BIGDECIMAL和BINARY，需选择参数名对应的绑定字段的参数类型。

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

    操作符

    选择您所需的操作符。

    说明

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

    示例

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

    描述

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

    是否必填

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

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

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

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

    说明

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

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

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

后续步骤

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

阿里云首页 智能数据建设与治理 Dataphin 相关技术圈