API开发

API的属性包含属性配置、执行配置、请求参数、返回参数，由于配置信息较多，控制台上将以4个页签展示。

• 属性配置

  名词	名词解释
  API名称（必选）	数据API的名称，支持汉字，英文，数字，下划线（_），且只能以英文和汉字开头，4~100个字符。
  描述（可选）	用于API的逻辑描述，如描述返回的是什么数据，用于什么场景。
  路径（必选）	该路径为API调用地址的组成部分。 路径只能以/开头，只支持英文、数字、下划线（_）、横杠（-），如/item/add。 API调用地址结构为：https://{分组域名}{路径}。 如路径定义为/item/test、分组域名为xxxx-cn-hangzhou.alicloudapi.com，则最终API调用地址为https://xxxx-cn-hangzhou.alicloudapi.com/item/test。
  返回格式（必选）	目前仅支持以JSON格式返回API的数据。
  请求方式（必选）	通用的API请求方式，支持的选项： POST GET 本示例的请求方式为GET。
  超时时间（必选）	执行API时的最大耗时，单位为毫秒，默认值为10000。 调用API时，当执行时间超过该参数值，将返回超时错误。该值最大允许30000（毫秒），即30秒。
  返回最大记录数（必选）	调用API允许返回的最大记录数。默认值为1000。 说明 当实例处于安全管控模式下，安全规则中同样定义了返回最大记录数，此时，API的最大记录数，不允许超过安全规则中的返回最大记录数。
  返回字段元数据	根据您的业务需求选择是或否，若您选择是，则在调用API允许返回字段的类型、长度等基本信息。
  返回执行详情	根据您的业务需求选择是或否。

• 执行配置

  名词	名词解释
  实例查询类型	实例查询的类型，支持的权限： 单实例查询：仅查询一个数据库实例。可以通过表引导模式和SQL脚本模式定义API。 跨实例查询：通过编写跨数据库查询DSQL，来实现多个不同实例数据的关联查询，详细信息，请参见官方文档。仅支持SQL脚本模式定义API。
  数据源	待查询的数据库。通过输入关键字，可查询当前用户有查询权限的数据库。 该参数仅当实例查询类型为单实例查询模式时显示。
  配置方式	选择API的配置方式，支持的选项： 表引导模式：通过可视化的方式选择表、字段，定义API的数据查询配置。 脚本模式：通过手动编写SQL脚本+变量的方式来定义API的数据查询配置。 说明 从表引导模式切换为脚本模式时，系统将提示切换模式将清空请求参数和返回参数。 该参数仅当实例查询类型为单实例查询模式时显示。
  选择表	表引导模式下，可选择需要执行查询的表。可通过输入关键字快捷查找表。 该参数仅当配置方式为表引导模式时显示。
  字段列表	该字段列表会展示当前选择的数据表中的所有字段，您可以通过勾选的方式，快速定义目标字段作为API的请求参数和返回参数。 该参数仅当配置方式为表引导模式时显示。
  查询SQL	您可以在此编写查询SQL。 SQL脚本支持变量的定义。通过定义变量，可映射成为API的请求参数。变量在SQL中，以${变量名}的方式书写。例如${category}，完整带变量的SQL为select item_id, item_name from ex_item where category=${category}。 在编写完成SQL脚本后，需要单击解析脚本按钮解析脚本的正确性以及变量定义。解析成功后，系统会自动基于定义的变量作为请求参数。 该参数仅在以下两种情况显示： 跨实例查询，且只支持DSQL语法，更多信息，请参见DSQL语法。 单实例查询的脚本模式，语法需要与选择的数据源语法类型一致。

• 请求参数

  名词	名词解释
  参数名称	调用API时的入参名称，支持英文、数字、下划线（_）、横杠（-），且只能以英文或下划线（_）开头，1~50个字符，默认为字段名。
  变量名称或字段名称	这里显示该参数来源，可来源于表引导模式的字段，也可来源于脚本模式的变量。
  不能为空	该项定义请求参数在调用时，是否为必需项。勾选则代表请求参数为必须输入项。 说明 当配置方式为脚本模式时，所有参数均为必需，不可去勾选；表引导模式时，则可选。
  描述	用于描述该请求参数。
  数据类型	包括字符串、整型、浮点三种基本类型，默认为字符串。 此参数的作用为：在调用时将校验请求参数值是否符合对应的类型，且在执行API时，保障SQL的正常执行。
  示例值	请求参数的示例值。 在生成SDK和文档时，供使用者阅读，便于正确调用API。
  默认值	当请求参数为可选时，如果存在该定义，则以该定义作为入参执行API。

• 返回参数
  说明 当前只支持读取表数据，因此返回参数列表的组合也代表了所执行数据查询的二维表结构。

  名词	名词解释
  参数名称	返回参数名称，支持英文、数字、下划线（_）、横杠（-），且只能以英文或下划线（_）开头，1~50个字符，默认为字段名。
  变量名称或字段名称	仅显示返回的字段名。
  描述	用于描述返回参数。
  数据类型	包括字符串、整型、浮点三种基本类型，默认为字符串。 此参数的作用为：系统把查询后的数据，按照此处定义进行数据转换，最终将数据写入返回的JSON中。
  示例值	返回参数的示例值。在生成SDK和文档时，供使用者阅读，便于正确了解API返回信息。

• 发布API
  单击操作列下的发布，单击确认，完成发布。

  说明 发布后的API处于上线状态，可使用SDK进行调用。由于API与API网关集成，因此发布后的API，可在API网关的控制台中看到，但不可编辑，否则将影响API的可用性。
• 修改API
  单击操作列下的修改，修改完成后，单击发布。属性配置的规则，请参见新增API。

  说明

  • 该操作支持修改API的任何属性，但修改API操作需要确保不影响线上正在调用的应用。如请求参数变更、返回参数变更，均可能影响API的调用。需要根据变更，调整调用API的参数请求和返回参数处理逻辑。
  • 修改后的API，需要进行重新发布才会生效。
• 删除API
  单击操作列下的删除，在弹出的对话框中，单击确认。

  说明 删除API的同时，会对API进行下线处理，也会同步删除API网关中对应的API。