向导模式

向导模式生成API即基于已创建的服务单元或逻辑表在产品界面进行简单的勾选配置即可快速生成API,无需编写任何代码。在服务单元或逻辑表中的字段可以直接作为API请求参数和返回参数的场景中,您可以使用向导模式生成API。本文为您介绍如何使用向导模式生成API。

前提条件

在开始执行操作前,需满足以下条件:

使用限制

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

注意事项

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

操作流程

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

    选择API的生成方式为模板向导模式。

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

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

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

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

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

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

    系统默认进入市场页面。

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

    image
  3. 新建API配置向导页面,选择生成API的方式为向导模式后,单击下一步

    image

步骤二:配置API基础信息

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

参数

描述

API名称

API名称命名规则如下:

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

  • 长度为4~42个字符。

  • 以字母开头。

  • 全局唯一。

请求方式

API请求方式包括GET和LIST:

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

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

数据更新频率

定义API返回数据的更新频率,选择每天每小时每分钟更新API返回的数据,便于调用方了解数据的时效性。

描述

填写对API简单的描述。

协议

当前,数据服务支持生成API接口协议包括HTTP和HTTPS。

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

  • HTTPS:即HTTP的安全版。HTTPS的安全基础是SSL,因此您需要配置独立域名的SSL证书。同时需确保独立域名的SSL证书有效,避免无法正常调用。

时时

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

缓存设置

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

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

在配置API请求参数返回参数过程中,您需要先确定API的入参和出参的来源(服务或单元逻辑表),再将入参和出参分别添加至请求参数返回参数区域,最后配置请求参数返回参数的基本信息。

  1. 参数配置面板,配置API请求参数返回参数服务单元Dataphin逻辑表中的取数逻辑。

    1. (可选)数据源类型支持服务单元Dataphin逻辑表

      选择了服务单元Dataphin逻辑表后,页面下方会为您展示已选择的服务单元或Dataphin逻辑表中所有的字段。

      服务单元

      image

      Dataphin逻辑表

      image

      参数

      描述

      模式

      支持BasicDev_Prod两种模式。

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

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

      数据源类型

      可选择服务单元Dataphin逻辑表

      • 当数据源类型选择服务单元时,需选择服务单元。支持复制全表字段或单个字段。

      • 当数据源类型选择Dataphin逻辑表时,需选择该逻辑表所在的业务板块及选中的板块下的逻辑表。

    2. 按照下图操作指引,选择API的入参并添加至请求参数区域后,再配置请求参数的基本信息。

      image

      参数

      描述

      参数名

      对外开放的参数,即用户访问API时直接使用的参数。命名规则如下:

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

      • 以字母开头。

      • 长度为1~64字符。

      绑定字段

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

      参数类型

      参数类型包括Double、Float、String、Date、Boolean、Int、Long、Short、Byte、Bigdecimal、Binary。您需要根据服务单元逻辑表中字段的类型选择对应的参数类型。

      服务单元字段类型与请求参数字段类型保持一致,您选择对应的字段类型即可;如果逻辑表的字段类型不在待选参数类型范围内,推荐您选择String。

      操作符

      调用API时对请求参数的处理方式。当前支持的操作符及含义请参见附录:支持的操作符

      示例

      填写请求参数值的示例,便于开发者理解。例如参数名称为ID,参数类型为Int,操作符为=,则示例处可以配置为5。

      描述

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

      是否必填

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

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

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

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

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

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

    3. 按照下图操作指引,选择API的出参并添加至返回参数区域后,再配置返回参数的基本信息。

      image

      参数

      描述

      参数名

      对外开放的参数,API返回时最终展示给用户的参数名称。命名规则如下:

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

      • 以字母开头。

      • 长度为1~64字符。

      绑定字段

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

      参数类型

      调用API时的数据格式。参数类型包括Double、Float、String、Date、Boolean、Int、Long、Short、Byte、Bigdecimal、Binary。您需要根据服务单元逻辑表中字段的类型选择对应的参数类型。

      服务单元字段类型与请求参数字段类型保持一致,您选择对应的字段类型即可;如果逻辑表的字段类型不在待选参数类型范围内,推荐您选择String。

      示例

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

      描述

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

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

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

附录:支持的操作符

操作符

描述

=

检查两个操作数的值是否相等,如果相等则条件为真。

>

检查左操作数的值是否大于右操作数的值,如果是则条件为真。

>=

检查左操作数的值是否大于等于右操作数的值,如果是则条件为真。

<

检查左操作数的值是否小于右操作数的值,如果是则条件为真。

<=

检查左操作数的值是否小于等于右操作数的值,如果是则条件为真。

!=

检查左操作数的值是否不等于右操作数的值,如果是则条件为真。

in

运算符用于把某个值与一系列指定列表的值进行比较。

like

like包括%like%、%like、like%:

  • %like%:表示忽略前后缀,进行字符匹配。

  • %like:表示忽略前缀,进行字符匹配。

  • like%:表示忽略后缀,进行字符匹配。

后续步骤

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

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