通过向导模式创建API（服务单元）

前提条件

基于服务单元生成，需先完成服务单元的创建。具体操作，请参见创建服务单元。

权限说明

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

使用说明

• 使用API分页查询时，需要设置字段排序以确保返回结果的顺序稳定，避免导致分页查询的部分结果重复及丢失；仅当使用API分页查询时，在API调试或测试页面展示分页参数（PageStart及PageSize）信息。

• 在API调用时，分页查询是否开启，均可使用PageStart及PageSize设置分页。

支持分页、排序的数据源

Y表示支持；N表示不支持。

是否必须指定排序：如果数据源类型需要强制指定排序，则在分页查询时，需要在API中配置参数或在调用时设置OrderByList参数指定排序。

注意事项

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

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

1. 在Dataphin首页，在顶部菜单栏选择服务 > 开发。

2. 选择项目，单击左侧导航栏API，在API页面，单击+新建API。

3. 在API创建方式选择对话框，选择服务单元API-向导模式后，单击确定。

步骤二：配置API参数信息

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

   API基本信息配置

   参数	描述
   API名称	填写API的名称。命名规则如下： 只能包含中文、字母、数字或下划线（_）。 长度为4~42个字符。 以字母开头。 全局唯一。
   请求方式	API请求方式包括GET和LIST： GET：请求服务器获取指定的某个资源。 LIST：请求服务器获取某一部分的资源。
   数据更新频率	定义API返回数据的更新频率，便于调用方了解数据的时效性，支持每天、每小时、每分钟更新API返回的数据。
   API分组	选择API需要归属的分组。如需创建，请参见创建服务分组。
   结果分页	当请求方式为List时，支持设置结果分页。开启后，请务必指定排序字段，确保返回查询结果的稳定，避免导致分页查询的部分结果重复及丢失；关闭后，API调试或测试页面不展示分页参数（PageStart及PageSize），您可以取消选中隐藏参数，展示分页参数。
   描述	填写对API的简单描述。不超过128个字符。
   协议	当前，数据服务支持生成API接口协议，包括HTTP和HTTPS。 HTTP：即超文本传输协议（HyperText Transfer Protocol），是应用最为广泛的网络协议。 HTTPS：即HTTP的安全版。HTTPS的安全基础是SSL，因此您需要配置独立域名的SSL证书。同时需要确保独立域名的SSL证书有效，避免无法正常调用。
   超时时间	超时时间用于监控API调用的时长。调用API过程中如果超过了设定的超时时间，则调用API时会报错，便于您及时发现并处理调用API的异常情况。异常情况查看，详情请参见查看及管理运维监控API。
   缓存设置	支持开启或关闭。开启后需配置缓存时长。默认300sec（秒），支持设置60秒~1000000秒（约277.78小时）之间的正整数。
   版本号	请填写API的版本号，每份配置信息会有所属版本号，以便于和上个版本信息对比。64字符以内。该API下版本号唯一。
   返回类型	默认JSON。

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

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

   1. 在参数配置区域，选择模式和服务单元后，页面下方会为您展示已选择的服务单元中所有的字段。

      参数	描述
      模式	支持Basic或Dev_Prod两种模式。 Basic模式下开发时、提交及发布线上均读取生产库。 Dev-Prod模式下开发及提交读取开发库，发布线上读取生产库。
      服务单元字段	支持复制全表字段或单个字段。异常字段用告警图标标识，您需要查看该字段所属的服务单元是否已发布至生成环境或该服务单元是否存在。

   2. 在双列表框的左侧列表中选择一个或多个字段后，单击图标，将已选择API的字段添加至右侧的请求参数列中，再配置请求参数的基本信息。

      

      参数	描述
      参数名	对外开放的参数，即用户访问API时直接使用的参数。命名规则如下： 包含字母、数字或下划线（_）。 以字母开头。 长度为1~64个字符。
      绑定字段	对外不可见的参数，API调用时实际访问的参数。
      参数类型	参数类型包括Double、Float、String、Date、Boolean、Int、Long、Short、Byte、Bigdecimal、Binary。您需要根据服务单元中字段的类型选择对应的参数类型。 服务单元字段类型与请求参数字段类型保持一致，您选择对应的字段类型即可。
      操作符	调用API时对请求参数的处理方式。当前支持的操作符及含义请参见附录：支持的操作符。
      示例	填写请求参数值的示例，便于开发者理解。例如：参数名称为ID，参数类型为Int，操作符为=，则示例处可以配置为5。
      描述	填写对请求参数的简单描述。
      是否必填	请求参数是否为调用API时的必填参数。 选择为否：调用API的语句中没有该参数也可以执行调用API的SQL语句。 选择为是：调用API的语句中没有该参数无法执行调用API的SQL语句。 例如，请求参数为id，请求参数为必填参数，返回参数为name；则执行以下语句会有不同的返回： select name from tableA,where id=5；：则返回对应的name字段及数据。 select name from tableA;：则SQL语句执行报错。

   3. 在双列表框的左侧列表中选择一个或多个字段后，单击图标，将已选择API的字段添加至右侧的返回参数列中，再配置返回参数的基本信息。

      

      参数	描述
      参数名	对外开放的参数，API返回时最终展示给用户的参数名称。命名规则如下： 包含字母、数字或下划线（_）。 以字母开头。 长度为1~64字符。
      绑定字段	对外不可见的参数，API调用时实际访问的参数。
      参数类型	调用API时的数据格式。参数类型包括Double、Float、String、Date、Boolean、Int、Long、Short、Byte、Bigdecimal、Binary。您需要根据服务单元中字段的类型选择对应的参数类型。 服务单元字段类型与请求参数字段类型保持一致，您选择对应的字段类型即可。
      示例	填写返回参数值的示例，便于开发者理解。
      描述	填写对返回参数的简单描述。

   4. 在双列表框的左侧列表中选择一个或多个字段后，单击图标，将已选择API的字段添加至右侧的排序设置列中，将需要排序的字段添加至排序设置区域。

      排序字段非必填，若开启分页查询，请务必指定排序字段，确保返回查询结果的稳定，避免导致分页查询的部分结果重复及丢失；若在请求中指定了排序参数，则以参数中设置的排序为准。

      

      参数	描述
      排序字段	选择服务单元中需要排序的字段。
      排序方式	支持升序、降序。
      操作	支持选中字段名称前的图标进行拖拽排序或选择操作列下的图标进行上下移动，图标从左到右依次为：上移、下移、删除。 说明 排序结果根据排序顺序从上往下优先级依次降低。 API中定义的排序设置与OrderByList公共请求参数同时生效，OrderByList公共请求参数的优先级高于API中定义的排序设置。 若API的请求方式为GET，排序后返回第一条结果数据。

2. 单击提交，校验API引用的字段在所属的服务单元中是否存在，校验通过后，完成API的生成。

附录：支持的操作符