文档

通过SQL模式创建API(Dataphin表)

更新时间:

SQL模式是基于Dataphin逻辑表,编写SQL语句创建API。本文为您介绍如何使用SQL模式生成API。

前提条件

MaxCompute计算引擎支持逻辑表创建API,需完成以下步骤:

  • 基于逻辑表生成API的场景中,需要完成逻辑表(维度逻辑表、事实逻辑表和汇总逻辑表)的创建。具体操作,请参见规范建模概述

  • 基于创建好的逻辑表,在集成中配置同步任务,具体步骤如下:

    • 运维 > 周期任务中选中逻辑表对应任务,选择补数据 > 补当前及下游任务,任务列表选择6层,全选任务列表,并在补数据实例查看是否运行成功。具体操作请参见附录:周期任务补数据

    • 即席查询中查看数据是否符合预期,确保逻辑表中有数据。具体操作请参见查询并下载数据

    • 在集成中配置同步任务,输入组件选择逻辑表输入配置(LogicalTable),输出组件选择MySQL输出组件,具体操作请参见配置LogicalTable输入组件配置MySQL输出组件

      配置完同步任务后,且成功发布后,可在数据服务创建逻辑表API并进行提交/发布。

使用限制

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

注意事项

API的请求参数和返回参数需从同一个Dataphin逻辑表中获取,否则后续无法正常调用该API。

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

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

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

    image.png

  3. API创建方式选择对话框,选择逻辑表API-SQL模式(Dataphin表)后,单击确定

步骤二:配置API参数信息

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

    API基本信息配置

    image.png

    参数

    描述

    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请求参数返回参数过程中,您需要先确定入参和出参的来源(Dataphin逻辑表),再编写API SQL并解析出请求参数返回参数,最后配置请求参数返回参数的基本信息。

    1. 参数配置页面,选择了模式Dataphin逻辑表后,页面下方会为您展示已选择的Dataphin逻辑表中所有的字段,便于您编写API SQL时参考。

      image.png

      参数

      描述

      模式

      需选择该逻辑表所在的业务板块及选中的板块下的逻辑表。支持BasicDev_Prod两种模式。

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

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

      逻辑表字段

      支持复制全表字段或单个字段。

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

      image.png

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

      • 模板一:仅查询和返回数据表中的字段。

        • 命令格式

          select <返回参数> from <数据表名> where <请求参数>=${请求参数值}
        • 使用示例

          --在数据表A中查询当c=id_card时,返回id_card和name。
          select 数据表A.id_card,数据表A.name from 业务板块A.数据表A where 数据表A.c=${id_card}
      • 模板二:查询和返回数据表包含的字段。

        • 命令格式

          select <返回参数> from <逻辑表名> where <请求参数> in (${请求参数值})
        • 使用示例

          --在数据表A中查询当c %in% id_card时,返回id_card和name。
          select 数据表A.id_card,数据表A.name from 业务板块A.数据表A where 数据表A.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 <逻辑表名> where <请求参数名1> like ${请求参数值1}
        • 使用示例

          --在数据表A中查询字段c %like% id_card时,返回字段a的最大值,参数名为c;返回a的最小值,参数名为d;返回a的总和,参数名为b。
          select max(数据表A.a) as c,sum(数据表A.a) as b ,min(数据表A.a) as d,count(*) as e from 业务板块A.数据表A where 数据表A.c like ${id_card}
      • 模板四:字段间的运算支持+(加法)、-(减法)、 * (乘法)、/(除法)、% (求余数)、 // (整除) **(幂次方),同时支持逻辑运算符and(与)和or(或)。

        • 命令格式

          select (<返回参数1>+<返回参数2>) as <别名>,(<返回参数2>+<返回参数3>) as <别名> from <逻辑表名> 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.a + 数据表A.b) as acd, (数据表A.b + 数据表A.c) as bcf from 业务板块A.数据表A where 数据表A.c=${id_card} and/or 数据表A.b>=${num} and/or 数据表A.c<=${num1}
      重要

      上述四种模板中API的请求参数和返回参数需从同一个逻辑表中获取,否则后续无法正常调用该API。

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

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

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

        image.png

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

      image.png

      参数

      描述

      参数名

      对外开放的参数。

      绑定字段

      对外不可见的参数,API调用时实际访问的参数。

      参数类型

      参数类型包括Double、Float、String、Date、Boolean、Int、Long、Short、Byte、Bigdecimal、Binary。您需要选择参数名对应的绑定字段的参数类型。

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

      示例

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

      是否必填

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

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

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

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

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

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

      描述

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

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

后续步骤

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

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

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