配置方式生成API
本节介绍如何通过配置方式生成API。
使用配置方式生成数据API简单且容易上手，您不需编写任何代码，通过产品界面进行勾选配置即可快速生成API。推荐对API功能的要求不高或者无代码开发经验的用户使用。
前提条件
已在页面，完成数据源的配置。
新建API目录
API目录是按一定次序编排记录的API索引，是反映类别、指导使用、检索API的工具，帮助API开发者对API服务进行有效的分类和管理。
- 在DataArts Studio控制台首页，选择实例，单击“进入控制台”，选择对应工作空间的“数据服务”模块，进入数据服务页面。
图1 选择数据服务
配置API基本信息
- 在DataArts Studio控制台首页，选择实例，单击“进入控制台”，选择对应工作空间的“数据服务”模块，进入数据服务页面。
图2 选择数据服务
- 在左侧导航选择服务版本（例如：专享版），进入总览页。
- 进入页面，单击“新建”，填写API基本信息。
表1 API基本信息 配置
说明
API名称
支持中文、英文、数字、下划线，且只能以英文或中文开头，3-64个字符。
API目录
一个特定功能或场景的API集合，类似文件夹，指定当前API保存的位置，后续可以在指定的API目录中检索当前API。
API目录是数据服务中API的最小组织单元，也是API网关中的最小管理单元。您可单击“新建”进行新建，也可选择新建API目录已创建的API分组。
请求Path
API访问路径，例如：/getUserInfo。
请求Path即完整的URL中，域名之后、查询参数之前的部分，如图3中的“/blogs/xxxx”。
在请求Path中，可以使用大括号{}标识路径中的参数作为通配符。如“/blogs/{blog_id}”表示/blogs后可以携带任何参数，例如“/blogs/188138”和“/blogs/0”均会匹配至/blogs/{blog_id}，由此API统一处理。
此外，相同域名下，不允许重复的请求路径出现。路径参数作为通配符时，名称不具备唯一性，例如“/blogs/{blog_id}”和“/blogs/{xxxx}”，会被视作相同路径。
参数协议
用于传输请求的协议，共享版支持HTTP或HTTPS协议，专享版支持HTTPS协议。
推荐选择HTTPS协议，HTTP安全性欠佳，可能会存在安全风险。
- HTTP属于基础的网络传输协议，无状态、无连接、简单、快速、灵活、使用明文传输，在使用上较为便捷，但是安全性欠佳。
- HTTPS是在HTTP协议上进行了SSL或TLS加密校验的协议，能够有效验证身份以及保护数据完整性。相对的，访问HTTPS的API，需要配置相关的SSL证书或跳过SSL校验，否则将无法访问。
请求方式
HTTP请求方式，表示请求什么类型的操作，包含GET、POST等，遵循resultful风格。
- GET：请求服务器返回指定资源，推荐使用GET请求。
- POST：请求服务器新增资源或执行特殊操作，仅在注册API时使用。POST请求当前不支持body体，而是直接透传。
描述
对API进行简要描述。
标签
对API设置标签。用于标记当前API的属性，创建后可以通过标签快速检索定位API。单个API最多可设置20个标签。
审核人
拥有API的审核权限。
单击“新建”，进入页面，新建审核人。
安全认证
创建API时，有如下三种认证方式可选。三种方式的区别在于认证方式和调用方法不同，推荐使用安全性更高的“APP认证方式”。- “APP认证方式”：API调用者通过APP认证方式调用API。Appkey & Appsecret安全级别高，推荐使用。
使用APP认证时，需要通过SDK访问，其中SDK访问提供了基于Java、Go、Python、JavaScript、C#、PHP、C++、C、Android等多种语言的SDK包。各语言调用API示例请参考使用APP认证调用API章节。
- “IAM认证”：需要借助IAM服务进行安全认证。IAM认证只允许华为云用户访问，安全级别中等。
使用IAM认证时，需要通过调用IAM服务的获取用户Token接口获取Token，然后通过在请求消息头中添加“X-Auth-Token”参数并将所获取的Token作为参数值，再通过API调用工具或SDK方式调用已发布的API。
- “无认证”：不需要认证。安全级别低，所有用户均可访问，建议仅在测试接口时使用，不推荐正式使用。若调用方为不可信任用户，则存在数据库安全风险（如数据泄露、数据库高并发访问导致宕机、SQL注入等风险）。
使用无认证方式时，无需鉴权认证信息。通过API调用工具或SDK方式，直接使用已发布API域名并填写入参即可进行调用。
服务目录可见性
发布后，所选范围内的用户均可以在服务目录中看到此API。
- 当前工作空间可见
- 当前项目可见
- 当前租户可见
访问日志
勾选，则此API的查询结果将会产生记录并被保留7天，可以在“运营管理 > 访问日志”处通过选择“请求日期”的方式查看对应日期的日志。
最低保留期限
API发布状态预留的最低期限，单位为小时，0表示不设限制。
如果需要停用/下线/解除授权，则停用/下线/解除授权时间必须选择在发布后的最低保留期限时间之后。选择时间后，停用/下线/解除授权会通知已授权用户。如果所有已授权用户均完成审核中心通知列表消息处理，或在应用中解绑与API的绑定关系，API就会停用/下线/解除授权；否则会以待停用/待下线/待解除授权状态，等待达到停用/下线/解除授权时间，再强制停用/下线/解除授权。
例如，最低保留期限设置为24小时，则此API发布后需要停用时，停用时间必须选择在发布24小时后，即发布第二天之后。如果期间内已授权用户已完成审核中心通知列表消息处理或解绑应用与API的绑定关系，则会直接停用；如果未完成，则会以待停用状态等待达到停用时间，强制停用。
入参定义
配置调用API需要输入的参数，此处定义后即为配置取数逻辑时的请求参数。
入参定义主要由参数位置、参数类型、是否必填以及默认值等组成。- 参数位置主要包括Query、Header、Path、Body四大类，另外还支持Static静态参数。
- Query是位于URL后的查询参数内容，以“?”开始，通过“&”连接多个参数。
- Header参数是位于请求消息头中的参数，常用于传递当前信息。例如host，token等。
- Path是位于请求路径中的请求参数，如果定义了Path参数，则需要在请求Path中也添加此参数，作为请求Path的一部分。
- Body是位于请求体内的参数，一般使用json格式表示。
- Static是不随API调用者的传值变化的静态参数，参数值由API授权时确定（如果授权时未配置参数值，则会使用API入参默认值作为替代）。
- 参数类型分为数值型Number与字符型String两大类。Number参数对应数据库中int、double、long等数值数据类型，String参数对应数据库中char、vachar、text等文本数据类型。
- 是否必填以及默认值。如果设定为必填，则API在访问时，必须传入指定参数；如果非必填，则在API访问时，未传入的参数，会使用默认值进行代替。
说明：入参定义中，参数大小限制如下：
- Query+Path，URL最大32KB
- Header，最大128KB
- Body， 最大128KB
实际配置中，需要根据所设计的调用API时请求参数情况来设置入参。例如，在用户表中根据用户ID查询用户信息时，请求Path设置为：/getUserInfo。可按照如下不同场景来配置入参：- API调用时请求参数为用户id，需要返回对应id的用户信息。
- 单击“添加”，参数名配置为id。
- 参数位置选择Query。
- 类型设置为Number。
- 是否必填选择必填。
- 默认值保持默认，无需填写。
- API调用时请求参数为用户id1和用户id2，需要返回id1-id2范围内的用户信息：
- 单击“添加”，参数名配置为id1。
- 参数位置选择Query。
- 类型设置为Number。
- 是否必填选择必填。
- 默认值保持默认，无需填写。
- 再次单击“添加”，按照id1参数的配置信息再配置id2。
- 配置好API基本信息后，单击“下一步”，即可进入API取数逻辑页面。
配置取数逻辑
- 选择数据源、数据连接、数据库和数据表，获取到需要配置的表。
- 配置参数字段。
选择好数据表之后，单击“参数设置”后的“添加”，添加参数页面自动列出这个表的所有字段，分别勾选需要设置为请求参数、返回参数和排序参数的字段，分别添加到请求参数、返回参数和排序参数列表当中。
另外，专享版数据服务支持返回总条数，开启后可返回取值脚本执行结果数据的总条数。
图4 添加参数
- 编辑请求参数信息。
请求参数主要分为三部分，绑定参数、绑定字段、操作符。在请求参数列表中，需要设置绑定参数和操作符。
- 绑定参数对外开放，选择为基本配置中定义的入参，是用户访问API时直接使用的参数。
- 绑定字段对外不可见，是所选的数据表中的字段，为API调用时实际访问的内容。
- 操作符则是用户访问API时，对绑定字段和绑定参数的处理方式。操作符左边为绑定字段，右边为绑定参数。当前支持的操作符及含义如下：
表2 支持的操作符 操作符
描述
=
检查两个操作数的值是否相等。
如果绑定字段和绑定参数相等则条件为真。
<>
检查两个操作数的值是否相等。
如果绑定字段和绑定参数不相等则条件为真。
>
检查左操作数的值是否大于右操作数的值。
如果绑定字段大于绑定参数，则条件为真。
>=
检查左操作数的值是否大于等于右操作数的值。
如果绑定字段大于等于绑定参数，则条件为真。
<
检查左操作数的值是否小于右操作数的值。
如果绑定字段小于绑定参数，则条件为真。
<=
检查左操作数的值是否小于等于右操作数的值。
如果绑定字段小于等于绑定参数，则条件为真。
%like%
%like%表示忽略前后缀，进行字符匹配。
如果绑定字段忽略前后缀，能匹配绑定参数，则条件为真。
%like
%like表示忽略前缀，进行字符匹配。
如果绑定字段忽略前缀，能匹配绑定参数，则条件为真。
like%
like%表示忽略后缀，进行字符匹配。
如果绑定字段忽略后缀，能匹配绑定参数，则条件为真。
in
in运算符用于把某个值与一系列指定列表的值进行比较。
如果绑定字段能匹配多个绑定参数中的值，则条件为真。
not in
in运算符的对立面，用于把某个值与不在一系列指定列表的值进行比较。
如果绑定字段无法匹配多个绑定参数中的值，则条件为真。
值得注意的是，请求参数可以通过复制并设置操作符，实现多个输入的绑定参数条件匹配绑定字段。
以图5为例，即为访问API时输入两个入参id1和id2，匹配id1和id2数值范围之间的x列值。
- 编辑返回参数信息。
- 参数名对外开放，可自定义，是API返回时最终展示给用户的参数名称。
- 绑定字段对外不可见，是所选的数据表中的字段，是API调用时实际返回的内容。
- 参数类型则是API调用时，数据的呈现格式，分为数值型和字符型两类。
图6 返回参数
- 编辑排序参数信息。
排序参数主要分为四部分，参数名、字段名称、是否可选以及排序方式，支持多个排序参数。多个排序参数时，表示当第一个排序参数相等时，再逐一用后续排序参数去排序，通过“参数设置”的“添加”进入添加参数界面，调整排序参数勾选顺序，可重新调整排序参数的顺序。
- 参数名可自定义，用于与字段名称关联。
- 字段名称对外不可见，是所选的数据表中的字段，是API调用时实际访问的内容。
- 是否可选决定了调用API时此排序参数是否必选，勾选则表示可以不使用此参数。
- 排序方式分为升序、降序以及自定义，表示了当前参数允许使用的排序形式。如果设置为升序或降序，在API测试或调用时，如果排序参数描述pre_order_by的值与此处设置不符，则会导致调用失败。
图7 排序参数
- 单击“下一步”，进行API测试页面。
测试API
- 填写入参取值。
图8 填写入参取值
- （可选）调整排序参数描述pre_order_by的值。
系统根据排序参数信息已给出默认值，默认升序排序。一般而言，排序参数描述pre_order_by的值填写形式为“排序参数参数名:ASC”或“排序参数参数名:DESC”，其中ASC表示升序，DESC表示降序，多个排序参数描述以“英文分号”进行分隔。
- pre_order_by是非必填参数，默认取必选排序字段升序作为排序的依据。
- 当配置pre_order_by参数值时，需严格按照排序参数列表中配置的排序参数顺序、可选属性和排序方式进行配置，否则会调用失败。
图9 调整排序参数描述pre_order_by的值
- （可选）调整分页参数值。
系统会对返回数据进行分页，pageSize表示分页后的页面大小，pageNum表示页码。默认按100的大小分页，返回第1页数据。
API调试时，page_size (系统默认) 最大为100，当page_size值大于100时，默认查出的数据仍为100条。
图10 调整分页参数值
- 完成API参数的配置并保存后，单击左下角的“开始测试”，可进入API测试环节。
填写参数值，单击“开始测试”，即可在线发送API请求，在右侧可以看到API请求详情及返回内容。
- 测试过程中，当数据服务API查询返回值超过默认30秒无结果时，会报超时错误。
- 如果测试失败，请仔细查看错误提示并做相应的修改重新测试。
完成API测试之后，单击“确定”，即成功生成了一个数据API。
修改API
生成API后，如果您需要修改API内容，可在“开发API > API目录”或“开发API > API管理”处选择对应API，单击“编辑”按钮进行修改API的相关操作。
仅当API处于已创建、已驳回、已下线、已停用的情况下才能进行API修改。
