基于数据集，通过可视化界面配置参数快速创建API，支持向量查询等功能。本文为您介绍如何使用向导模式生成API。
前提条件
需购买非结构化数据功能和数据服务功能才能使用数据集API。
需在研发 > 数据研发 > 数据集中创建并提交数据集，详情请参见数据集。
权限说明
数据服务的项目管理员和开发用户支持生成API。
注意事项
API的请求参数和返回参数需从同一个数据集中获取，否则后续无法正常调用该API。
步骤一：选择生成API的方式
在Dataphin首页的顶部菜单栏，选择服务 > API开发。
在左上角选择项目，单击左侧导航栏API服务，在API页面，单击+新建API。
在新建API对话框，选择数据集API-向导模式（数据集）。
步骤二：配置API参数信息
在新建API页面，配置API基本信息和参数配置。
API基本信息配置
参数
描述
API名称
填写API的名称。命名规则如下：
只能包含中文、字母、数字或下划线（_）。
长度为4~100个字符。
以字母开头。
全局唯一。
操作方式
API操作类型包括GET和LIST：
GET：请求服务器获取指定的某个资源。
LIST：请求服务器获取某一部分的资源。
数据更新频率
定义API返回数据的更新频率，便于调用方了解数据的时效性，支持的更新频率为每天、每小时、每分钟以及自定义，若选择自定义，支持输入不超过128个字符。
API分组
选择当前项目下配置的API分组，如需创建，请参见创建服务分组。
结果分页
当请求方式为List时，支持设置结果分页。开启后，请务必指定排序字段，确保返回查询结果的稳定，避免导致分页查询的部分结果重复及丢失；关闭后，API调试或测试页面不展示分页参数（PageStart及PageSize），您可以取消选中隐藏参数，展示分页参数。
描述
填写对API的简单描述。不超过128个字符。
协议
数据生成API的接口协议，支持HTTP协议。
HTTP：即超文本传输协议HTTP（HyperText Transfer Protocol），是应用最为广泛的网络协议。
调用模式
用于客户端和服务器之间的通信，以获取或处理数据。支持选择同步调用。
同步调用：客户端发送请求后，必须等服务器返回结果后才能继续执行其他请求，针对复杂查询语句，响应时间较长且在等待过程中会占用服务器连接数，造成服务器压力。适用于实时性要求高、处理时间短的场景。
超时时间
用于监控API调用的最大时长。默认为3秒，支持设置的时间范围为3到60秒的正整数。
调用API过程中如果超过了设定的超时时间，则调用API时会报错，便于您及时发现并处理调用API的异常情况。异常情况查看，详情请参见管理运维监控API。
最大返回条数
当操作类型为LIST时支持该配置项。API最大的返回条数为10000条。支持输入1~10000之间的正整数。
缓存设置
支持开启或关闭。开启后需配置缓存时长。默认300秒，支持设置60秒~1000000秒（约277.78小时）之间的正整数。
版本号
请填写API的版本号，每份配置信息会有所属版本号，以便于和上个版本信息对比。该API下版本号唯一。命名规则如下：
不超过64个字符。
支持输入大小写英文字母、数字、下划线（_）、半角句号（.）、短划线（-）。
返回类型
默认JSON。
返回SQL
控制API响应中是否包含实际执行的SQL语句。
选择是（启用）：API响应中将返回数据库实际执行的物理SQL语句。
选择否（禁用）：API响应中将展示原始SQL脚本。
API请求参数和返回参数配置
在配置API请求参数和返回参数的过程中，您需要先确定API的入参和出参的来源（数据集），再将入参和出参分别添加至请求参数和返回参数区域，最后配置请求参数和返回参数的基本信息。
在参数配置区域，配置参数后，下方列表会为您展示已选择数据集中的所有字段。
参数
描述
模式
支持Basic模式。Basic模式下开发、提交均读取生产库。
项目
选择对应模式下的项目。
数据集
选择对应项目下已发布的数据集及版本。仅支持表数据集和混合数据集。
数据集对应字段
为您展示所选数据集对应的字段。URL字段以
图标标识；向量字段以
图标标识。操作
单击打开数据预览面板，系统默认返回当前数据集的前100条数据，支持选择返回10、50、100、500、1000条数据。
将鼠标悬停数据集字段，单击请求参数或返回参数，将数据集字段添加至右侧的请求参数或返回参数列表。
当数据集字段为向量字段时支持配置向量查询。向量查询是指根据用户输入的查询文本，系统将基于向量字段配置的Embedding模型把文本转换为向量，在所有已开启向量查询字段上进行独立检索，并对各字段检索结果进行加权融合返回最终结果。单击展示向量配置或请求参数列表绑定字段下的向量查询，打开向量字段权重配置列表，为向量字段进行权重配置。
向量查询：开启后，当前字段开启向量查询，并在请求参数列表自动生成
query和top_k请求参数，返回参数列表自动生成_score返回参数。query：用于记录输入的查询文本。top_k：用于记录相似度最高的前K个返回结果。_score：用于量化查询文本与返回结果之间的匹配程度。
权重：用于分配给不同向量字段的重要系数，可决定该字段的匹配程度对最终总得分的影响。建议各字段权重之和为1.0。
距离度量：在向量检索中用于计算两个向量之间相似度的数学算法，在向量空间中，距离越近（夹角越小），表示两者语义越相近。支持选择余弦相似度、欧式距离、内积。
余弦相似度：适用于对文本长度不敏感的语义检索场景。例如，文档搜索、问答匹配、语义去重等。
欧式距离：同时受向量方向和长度（数值大小）影响，若两个向量方向相同但长度差异巨大，则会判断为不相似。适用于对数值幅度敏感的场景。
内积：用于计算两个向量对应维度的乘积之和，计算速度快。适用于高性能要求的检索场景。
最低分数阈值：用于管控最终返回的检索结果，当检索结果高于或等于设定的阈值时，结果返回；若低于阈值，则过滤结果。
参数
描述
请求参数
参数名称
对外开放的参数，即用户访问API时直接使用的参数，命名规则如下：
参数名称唯一。
包含字母、数字或下划线（_）。
以字母开头。
长度为1~64个字符。
绑定字段
对外不可见的参数，API调用时实际访问的参数。
参数类型
为您展示数据集对应的字段类型。
参数类型包括double、float、string、Date(yyyy-MM-dd HH:mm:ss)、Boolean、int、long、short、byte、BigDecimal和binary。
数据集字段类型与请求参数字段类型保持一致，您选择对应的字段类型即可。
操作符
调用API时对请求参数的处理方式。支持的操作符及含义请参见API开发支持的操作符。
默认值
若参数值未指定，则使用默认值（未设置时为NULL），支持输入不超过1000个字符。
示例
填写请求参数值的示例，便于开发者理解。例如：参数名称为ID，参数类型为Int，操作符为=，则示例处可以配置为5。支持输入不超过1000个字符。
描述
填写对请求参数的简单描述。支持输入不超过1000个字符。
是否必填
请求参数是否为调用API时的必填参数。
选择否：调用API的语句中没有该参数也可以执行调用API的SQL语句。
选择是：调用API的语句中没有该参数无法执行调用API的SQL语句。
例如，请求参数为id，请求参数为必填参数，返回参数为name；则执行以下语句会有不同的返回：
select name from tableA,where id=5；：则返回对应的name字段及数据。select name from tableA;：则SQL语句执行报错。
操作
query和top_k向量字段删除后，支持恢复操作，不支持修改名称、参数类型等操作。返回参数
参数名称
对外开放的参数，API返回时最终展示给用户的参数名称。命名规则如下：
参数名称唯一。
包含字母、数字或下划线（_）。
以字母开头。
长度为1~64字符。
绑定字段
对外不可见的参数，API调用时实际访问的参数。
参数类型
调用API时的数据格式。
参数类型包括double、float、string、Date(yyyy-MM-dd HH:mm:ss)、Boolean、int、long、short、byte、BigDecimal、binary和vector。
数据集字段类型与返回参数字段类型保持一致，您选择对应的字段类型即可。
示例
填写返回参数值的示例，便于开发者理解。支持输入不超过1000个字符。
描述
填写对返回参数的简单描述。支持输入不超过1000个字符。
操作
_score向量字段删除后，支持恢复操作，不支持修改名称、参数类型等操作。
在双列表框的左侧列表中选中一个或多个字段后，单击底部的更多-排序字段，将已选中的数据集字段添加至右侧的排序字段列。
排序字段非必填，若开启分页查询，请务必指定排序字段，确保返回查询结果的稳定，避免导致分页查询的部分结果重复及丢失；若在请求中指定了排序参数，则以参数中设置的排序为准。
参数
描述
排序字段
选择数据集中需要排序的字段。
排序方式
支持升序、降序。
操作
支持选中字段名称前的
图标进行拖拽排序或选择操作列下的图标进行上下移动，图标从左到右依次为：上移、下移、删除。说明排序结果根据排序顺序从上往下优先级依次降低。
若API的请求方式为GET，排序后返回第一条结果数据。
单击提交，校验API引用的字段在所属数据集中是否存在，校验通过后，完成API的生成。