通过向导模式生成API

数据服务支持通过向导模式或脚本模式生成API,相对于脚本模式,您无需编码能力,可以可视化地配置API。本文为您介绍如何通过向导模式生成API。

前提条件

配置API前,请先在工作空间管理 > 数据源管理页面配置数据源。详情请参见配置数据源

背景信息

如果您存在个性化查询需求,您可以通过自定义SQL脚本模式创建API,自行编写API的查询语句。在脚本模式下,支持多表关联、复杂查询和聚合函数等功能。例如,当请求参数为某字段区间时,您可以使用脚本模式配置API。

进入数据服务页面

登录DataWorks控制台,切换至目标地域后,单击左侧导航栏的数据服务,在下拉框中选择对应工作空间后单击进入数据服务

生成API

  1. 服务开发页面,鼠标悬停至image.png图标,单击新建API > 生成API

    您也可以打开相应的业务流程,右键单击API,选择新建API > 生成API

  2. 生成API对话框中,配置各项参数。

    参数

    描述

    API模式

    包括向导模式脚本模式,此处选择向导模式

    API名称

    支持中文、英文、数字、下划线(_),且只能以英文或中文开头,4~50个字符。

    API Path

    API存放的路径,即相对于服务host,API的请求路径。例如/user

    说明

    支持英文、数字、下划线(_)和连字符(-),且只能以( /) 开头,不得超过200个字符。

    协议

    支持HTTPHTTPS

    如果您需要通过HTTPS协议调用API,请您发布API至网关后,在API网关控制台绑定独立域名,并上传SSL证书。详情请参见支持HTTPS

    请求方式

    支持GETPOST

    说明

    请求方式选择GET时,请求参数位置仅支持选择QUERY。当请求方式选择POST时,请求参数位置支持选择QUERYBODY

    返回类型

    仅支持JSON返回类型。

    可见范围

    包括工作空间私有

    • 工作空间:该API对本工作空间内的所有成员可见。

    • 私有:该API仅对API的负责人可见,且暂不支持授权。

      说明

      如果设置可见范围为私有,在目录树中,仅自己可见,工作空间内的其他成员不可见。

    标签

    标签列表中选择相应的标签,详情请参见创建及管理API标签

    说明

    标签名称支持汉字、英文、数字和下划线(_),您最多可以设置5个标签,且每个标签不超过20个字符。

    描述

    对API进行简要描述,不得超过2000个字符。

    目标文件夹

    存放API的目录,可以在下拉列表选择已创建的业务流程,选定后,会生成API的存放路径。默认格式为:“业务流程/业务流程名称/API”,例如业务流程/ceshi/API

  3. 单击确定

配置API

  1. 双击打开API的编辑页面,在选择表区域,配置数据源类型数据源名称数据源环境数据表名称等参数。

    不同数据源类型的配置参数略有不同,具体配置参数以界面为准。选择表

    说明
    • 您需要提前在数据集成中配置好数据源,数据表下拉列表支持表名搜索。

    • 标准模式工作空间支持在数据源环境配置项选择访问开发或生产环境数据源,详情请参见必读:简单模式和标准模式的区别

    • 对于MaxCompute类的数据源表,您可以使用DataWorks数据服务的加速服务,或MaxCompute的MCQA加速服务进行加速,选择加速服务进行加速时,您需要先创建加速项,操作详情请参见加速服务

    • 创建好API后,会自动跳转至数据表配置页面,您可以直接进行配置。

  2. 选择参数区域,设置请求参数和返回参数。

    您选择数据表后,选择参数区域会自动显示该表的所有字段。根据自身需求,分别选中相应的字段设为请求参数设为返回参数,添加至请求参数和返回参数列表中。选择参数

    说明

    若数据源类型为HBase,选择参数区域会自动显示表中的所有列族(Family)。

    • 如需实现按照列族的查询(示例逻辑:get 'Student', 'StudentA', 'Info' ,'Address'),直接勾选目标列族(Family)来设为返回参数即可。

    • 如需实现按照列名的查询(示例逻辑:get 'Student', 'StudentA', 'Info:age' ,'Info:grade' ),需要点列族(Family)操作中的新增列名按钮,将目标列名(Column)手动添加至列表中,并勾选目标列名(Column)设为返回参数

    如果您需要对字段进行排序,单击相应字段后的添加到字段排序,将其添加至排序字段列表中。排序

    您可以根据数据表中的指定字段对API的返回结果进行排序。当您的排序列表中有多个字段时,序号越小的字段,排序的优先级越高,您可以通过上移下移操作来调整排序字段的优先级。对于每个排序字段,您均可以选择升序降序的方式进行排序。

  3. 单击API编辑页面右侧的请求参数,配置各项参数。

    说明
    • 进行结果预览前请设置API参数的示例值、默认值、描述等信息。

    • 尽量设置有索引的字段为请求参数。

    请求参数

    参数

    描述

    参数名称

    请求参数的名称,支持英文、数字、下划线、连字符(-),且仅支持以英文开头,不能超过64个字符。

    绑定字段

    默认不可以修改。如果您需要修改绑定字段,请使用脚本模式。详情请参见:通过脚本模式生成API

    参数类型

    包括STRINGINTLONGFLOATDOUBLEBOOLEAN

    参数位置

    包括QUERYBODY

    说明

    当有一个或多个参数位置选择BODY时,需要对BODY位置的参数进一步设置Content-Type来定义调用方在消息体中的传参格式。

    Content-Type包括:

    • application/json;charset=utf-8(JSON格式)

    • application/xml;charset=utf-8(XML格式)

    • application/x-www-form-urlencoded;charset=utf-8(FORM格式)

    操作符

    操作符用于表示请求参数和实际赋值之间的关联和比较。您可以选择以下操作符:

    • 等于:请求参数等于实际赋值。

    • LIKE:为请求参数搜索某种指定模式。

    • IN:为请求参数规定赋值集合。

    • NOT IN:请求参数不在赋值集合中。

    • NOT LIKE:请求参数不在该指定模式中。

    • !=:请求参数不等于实际赋值。

    • >:请求参数大于实际赋值。

    • <:请求参数小于实际赋值。

    • >=:请求参数大于或等于实际赋值。

    • <=:请求参数小于或等于实际赋值。

    说明

    选择表区域的数据源类型配置为Table Store时,操作符仅支持选择等于

    是否必填

    该请求参数是否必填。

    示例值

    该请求参数的示例值。

    默认值

    该请求参数的默认值。

    描述

    该请求参数的简要说明。

  4. 单击API编辑页面右侧的返回参数,配置各项参数。

    返回参数

    1. 配置返回参数。

      参数

      描述

      参数名称

      返回参数的名称,支持英文、数字、下划线、连字符(-),且仅支持以英文开头,不能超过64个字符。

      绑定字段

      默认不可以修改。

      参数类型

      包括STRINGINTLONGFLOATDOUBLEBOOLEAN

      示例值

      该返回参数的示例值。

      描述

      该返回参数的简要说明。

    2. 高级配置区域,设置是否返回结果分页

      • 如果不开启返回结果分页,则API默认最多返回2000条记录。

      • 如果返回结果可能超过2000条,请开启返回结果分页功能,开启后,您可以进入右侧导航栏的服务资源组页面,根据资源组类型设置单页条数上限。

      开启返回结果分页后,会自动增加以下公共参数:

      • 公共请求参数

        • pageNum:当前页号。

        • pageSize:页面大小,即每页记录数。

      • 公共返回参数

        • pageNum:当前页号。

        • pageSize:页面大小,即每页记录数。

        • totalNum:总记录数。

      说明

      API允许不设置请求参数,当无请求参数时,必须开启返回结果分页

  5. 配置过滤器。

    当您需要对API的请求参数进行预处理或对查询结果进行二次加工时,您可以在API编辑页面的右侧导航栏中,单击过滤器,根据需要勾选使用前置过滤器使用后置过滤器,并选择函数类型后,单击前置过滤器或后置过滤器右侧的下拉框选择目标函数(可添加多个函数,执行时会按添加顺序对参数进行处理),完成后,您可以单击API返回结果预览查看使用过滤器后的结果是否符合预期。创建和使用过滤器详情请参见:创建Aviator函数创建Python函数

    说明
    • 当使用Python函数作为过滤器时,请先开通DataWorks专业版及以上版本,并使用公共数据服务资源组。

    • 当使用Aviator函数作为过滤器时,无DataWorks版本限制,但需要使用独享数据服务资源组。

    • 若在过滤器的下拉列表中无法获取目标函数,请检查目标函数是否已发布,或尝试新建函数并发布。发布函数

    过滤器

  6. 配置服务资源组。

    1. 在API编辑页面的右侧导航栏中,单击服务资源组,您可以在资源组类型区域配置API调用时使用的资源组类型。

      支持您选择独享服务资源组公共服务资源组独享服务资源组可以在列表中选择目标资源组名称。公共服务资源组不可选择资源组名称,由DataWorks内部自动维护。API

      说明

      若在列表中无法选中目标资源组名称,请进入DataWorks控制台通过“修改归属工作空间”将资源组与工作空间进行绑定。

    2. 环境配置区域,您可设置内存超时时间单次请求数据条数上限

      • 所选DataWorks服务资源组和API网关实例的类型不同,允许设置的超时时间上限不同:

        • API网关共享实例:公共服务资源组不超过30000ms,独享数据服务资源组不超过30000ms。

        • API网关专享实例:公共服务资源组不超过30000ms,独享数据服务资源组不超过90000ms。

      • 所选服务资源组类型不同,允许设置的单页条数上限不同:

        • 如果选择公共服务资源组,开启分页后的每页数据记录最多支持2000条。

        • 如果选择独享服务资源组,开启分页后的每页数据记录最多支持10000条。

  7. 单击工具栏中的保存图标,保存API后,所选资源组将在测试时生效。

    配置API后,您可以对其进行测试。详情请参见测试API

    测试成功后,单击右上方的提交

    在API编辑页面的右侧导航栏中,单击版本,找到待申请版本单击申请发布跳转到申请页面,申请类型默认为发布数据服务API,填写申请原因后单击申请权限完成发布申请。

    说明

    工作空间定义审批流后需要走流程审批才可以发布API,详情请参见:审批中心概述

    发布API后,服务资源组的配置即可在调用API时生效。

    您还可以在服务开发页面左侧目录树中对目标API进行克隆和删除等操作。您也可以在服务管理页面,展开API列表,查看已发布API的详情。详情请参见查看、删除、移动、克隆、批量操作、代码搜索API

转换向导模式为脚本模式

您可以转换向导模式生成的API为脚本模式:

  1. 服务开发页面,展开目标API所在的业务流程 > API

  2. 双击相应的API名称,打开该API的编辑页面。

  3. 单击工具栏中的转换脚本图标。

  4. 提示对话框中,单击确认,您可以在编写查询SQL区域,查看转换后的SQL语句。

    重要
    • 数据服务仅支持转换向导模式配置的API为脚本模式。

    • 向导模式转换为脚本模式后,无法回退至向导模式。