创建

创建API有以下几种方式：向导模式、脚本模式、同时可以将已有API注册至平台（便于统一管理）。

另外，基于NoSQL类数据源（HBase、Elasticsearch、MongoDB、Redis、Solr）的API配置过程与普通API不太相同，在本文后半部分的NoSQL类API的配置列出

操作入口

进入「API管理->API管理->API」页面，点击「新增API」，如下图所示：

点击「生成API」按钮后，需选择向导模式或脚本模式。

API生成

3种方式的差异与适用场景

向导模式：适合单张表的简单逻辑查询，通过勾选的方式配置单张表的原生字段从而快速生成API，可视化易上手。
脚本模式：支持多张表关联输出、复杂查询条件及聚合函数操作等，通过SQL代码的方式配置API，灵活自定义。
注册API：支持将外部已有API注册至API网关，在本平台中进行API的统一管理调用。

生成API

生成API的页面内容如下图所示：

基本信息

所属类目：API的所属分类，本平台可以将不同的API以树形结构进行分类查看，分类的管理可查看类目管理。这里的所属类目仅是当前API所属项目内的分类，与API市场的类目不同。
API名称：只能以字母，数字，下划线组成，不支持中文，长度为2-64个字符之内，API名称将会参与到API的URL拼接中，所以仅支持上述字符。
API中文名称：可以使用中文对API进行描述，便于查找，不超过64个字符，不能包含空格。
API描述：对API的描述。
API path：即API的调用路径。填写后，API调用URL中将自动拼接API path，便于通过URL识别调用的API，API path只支持填写2层。API URL的完整组成元素可查看URL的组成元素
API path默认值：若勾选此默认值，系统将按照API所在的目录层级绑定的标识来自动拼接URL，详情可参考URL的组成元素。
API标签：对API打标签，便于快速地找到所需申请的API。单击输入框时自动显示已存在的标签，并可根据输入内容自动搜索匹配，便于复用标签，若没有所需标签，直接输入后，按回车后，自动创建一个新的标签。
API市场分类：当API发布至市场时的所属分类，与本项目内的所属类目相互独立，互不影响。便于维护2套类目，一套对外、一套对内。

:::注意

由于API名称参与调用URL的拼接，修改名称，再次发布API时，API的URL将会改变，注意下游的业务方需配合API URL的调整，详情可参考URL的组成元素

:::

API参数

协议：支持HTTP和HTTPS两种，若使用HTTPS协议，则需联系运维同学修改配置即可，HTTPS的证书需自行准备。
请求方式：可支持POST、GET两种。
返回类型：仅支持JSON。
超时时间：当后台请求数据时，超出此时间时将计为超时。单位为秒，默认值3秒，超时时间不建议设置较长，大量的API，或者请求频率高的API，设置的超时时间过长，会对系统稳定性有不良影响。

安全策略与限制

单用户每秒调用次数上限：分为每秒次数和每分次数，例如可设置为单个用户对API的调用每秒不超过2000次或每分钟不超过2000次，防止短时间、高频率的调用影响服务稳定。
安全组：安全组是将一组设置为白名单或黑名单的IP地址。将API绑定至安全组，可限制此API允许（不允许）安全组内的IP地址调用，安全组可多选，提升API调用的安全性。可参考安全组查看详细描述。
传输加密：API返回给调用方的数据是否加密，可在3种策略中选择一种：不加密（默认）、RSA+AES加密、SM2+AES加密。不同加密方式的区别与使用，可参考传输加密。
允许使用USER-TOKEN认证：每个用户有一个固定的USER-TOKEN，用户调用不同的API，可以只传递一个USER-TOKEN完成认证。USER-TOKEN的详细描述可参考API调用与认证。

向导模式参数

向导模式的API只支持使用单表的字段进行数据查询，当需要多表查询，或复杂查询时，请使用自定义SQL模式。向导模式、自定义SQL模式可支持的数据库范围，详见支持的数据源

数据源配置：选择此API基于的数据源类型、具体数据源、schema、表。
忽略语法校验：勾选后，系统将不再校验输入输出字段在表中是否存在，若字段不存在则判定为无效字段，不进行报错。不支持忽略ElasticSearch的语法校验。
格式化语句将写入的：SQL语句格式化为对应数据库SQL书写的标准格式，不支持NoSQL类查询语句的格式化。
输入参数：点击「新增参数」，系统自动读取源表的字段信息，可快速添加输入参数。
- 参数名称：向导模式下每个输入参数绑定一个字段，输入参数名默认与字段名相同，同时支持修改，参数名称只能由字母、数字、下划线及 . [ ]组成。
- 操作符可支持如下几种：=、>、>=、<、<=、!=、in、not in、like、not like,当用户输入操作符无法解析时，默认显示为--，可自行调整操作符的展示，注意此处仅作展示，操作符调整后不会影响SQL执行逻辑。当输入in、not in操作符时，可在入参中传入多个值，用英文逗号分开，系统在进行SQL拼接时，会拼接为in ('value1', 'value2')。例如：某个API的入参id的操作符为in，则入参传值可以为：
```
{
    "inFields":
    {
        "id": "i001,i003"
    }
}
```
  在页面测试时，填写的值也是i001,i003，用英文逗号分开，系统会将SQL拼接为：
```
select ... from t where id in ('i001', 'i003');
```
  注意，这里的例子中，id的字段类型为字符串类型，若为int等整型，则系统拼接时不会添加引号，而是会拼接为in (10, 20)这样的格式。
  caution
  in、not in操作符目前仅支持英文逗号分隔符，不支持指定分隔符或者进行转义。
- 必填：说明此参数是否必传，对于必填的参数，若入参中不存在对应的key，则会报返回码103（完整的返回码可参考返回码释义）。注意入参中「key值不存在」与「空值」的差异，例如：
```
//*************  key存在，值为NULL   ************//
{
    "inFields":
    {
        "name": "",   // 这里的name的key是存在的，后面的value为空，相当于值为NULL
        "age" : 10
    }
}


//*************  key不存在   ************//
{
    "inFields":
    {
                     // 这里的name的key不存在，则需配置为非必填入参
        "age" : 10
    }
}
```
- 行级权限：选择本字段应用哪个行级权限标识，详细的行级权限使用方式可参考行级权限。
- 说明：对入参的说明描述。
- 检验规则：提供了一种支持用户自定义检验规则的功能。在发起API调用前，系统会根据用户提供的正则表达式对输入内容进行校验，校验不通过则调用失败。此功能的应用范围包括：创建API时的测试API/服务编排、API的调用预览、测试与正式API的调用。在接收到API调用请求时，网关会优先进行输入参数的校验（如果有配置），将输入参数值代入用户提供的正则表达式和计算表达式进行计算，如果不满足规则，则不会向数据库发起查询，并返回调用失败（新增一个状态码）；如果满足规则，则继续后续的调用流程。例如：校验手机号“^1[34578]\d{9}$”。
- 默认值：对输入参数设置默认值，设置了默认值的输入参数，当用户调用api但没有对此参数传值时，使用此默认值进行数据库查询。
输出参数：点击「新增参数」，系统自动读取源表的字段信息，可快速添加输入参数。
- 参数名称：与输入参数的参数
- 数据预览：此参数可以控制申请API的用户，是否能在API市场预览这个字段的数据。API在发布至API市场后，勾选预览的字段，申请的用户才能进行预览。
  - 注意此参数只在预览时起作用，实际调用将按照用户配置的输出参数来返回数据。
  - 在API测试步骤的「将测试结果作为JSON样例保存」选项，若选中，则申请API的用户可以在API市场的页面预览返回的数据样例，而样例数据中可能存在禁止预览的部分，为避免此问题，请注意调整API测试样例的内容。
  - 用户开启「允许用户在API市场进行数据预览」选项时，才能勾选预览字段。
- 说明：对输出参数的说明描述。
输出结果排序：可选择某个字段对查询结果进行排序，支持选择多个字段，并配置为升序或降序。默认不排序。
:::注意
- 不排序时，多次执行简单查询可能出现重复数据。
- 若按照一个或多个字段排序时，排序操作可能导致较大的数据库资源消耗。
:::
高级配置
- 返回结果分页：当查询结果数据量较大时，需进行分页查询并返回，调用时在入参中指定pageNo、pageSize2个参数来指定分页编号和每页的记录数。若不勾选，则仅返回前1000条结果，若需要调整此结果的数量，需联系运维修改服务配置并重启API平台。
- 显示返回结果JSON样例：用户勾选该选项以后，可在该API的详情界面展示所返回的JSON样例。
- 返回结果携带分页参数：在返回结果中携带分页的信息，包括如下几个参数：
  - totalPage：本次查询结果，一共有多少页
  - pageSize：每一页的记录数，即入参中的pageSize
  - totalCount：当前SQL的查询结果集的总记录数（注意不是整张表的记录数）
  - currentPage：当前查询的是第几页的数据，即入参中的pageNo
  - 这几个参数的关系，可以看如下2个场景：
  返回结果举例：
```
//*************  场景1：大结果集分多页   ************//
//某张表共有1万条记录，当前SQL查询出998条数据，入参的分页信息为：
//pageNo=5
//pageSize=10
//返回结果的信息为
"page": {
        "totalPage": 100,   //查询结果集998条记录，每页10条，可分为100页，最后一页只有8条记录
        "pageSize": 10,     //入参设置的每页10条记录
        "totalCount": 998,  //查询结果998条记录
        "currentPage": 5    //当前查询的是第5页的数据
    },


//*************  场景2：小结果集   ************//
//某张表只有3条记录，当前SQL查询出1条数据，入参的分页信息为：
//pageNo=3
//pageSize=10
//返回结果的信息为
"page": {
        "totalPage": 1,   //查询结果集只有1条记录，每页10条，只能分为1页，且只有1条记录
        "pageSize": 10,   //入参设置的每页10条记录
        "totalCount": 1,  //查询结果只有1条记录
        "currentPage": 3  //当前查询的是第3页的数据，注意这里实际上是查询不出结果的，因为只有一页、一条记录，但入参是查询第3页的数据，将为空。若向查询出数据，此时入参的pageNo必需为1才行
    },
```
- 返回结果携带 Request Header 参数：若勾选此选项，在返回结果中将增加请求中header的信息，见本页的API测试一节中的示例。
- 允许用户在API市场进行数据预览、允许API市场的数据预览显示SQL：是否允许用户在API市场页面进行调用并预览查询结果。若允许预览结果，则还可以控制是否向申请API的用户暴露底层查询的SQL语句（requestSQL）。API市场的详细描述可参考API市场
- 允许用户配置输入参数校检表达式。
  勾选此项配置输入参数校验表达式可在每次API发起调用前对多个输入参数进行校验，若校验不通过将自动中止查询流程，调用失败。
  支持编写多个表达式（每行一个），参数用”${}”标识，例如：从2022年12月20日开始，限制使用时间不超过7天。
```
  ${end_day} - ${start_day} < 7
  ${start_day} > 20221220
```

脚本模式参数

脚本模式现支持DQL（数据查询）与DML（数据写入）两种类型，适用于单表查询无法满足，通过SQL加工、多表关联等场景。

DQL模式

仅支持输入一条SELECT(不区分大小写)的完整的语句；不支持 INSERT INTO、DELETE、UPDATE 等DML语句。
API返回参数：SELECT查询的字段即为API返回参数。如果使用 as 语句定义了字段别名，则API返回参数名称为 as 语句后的字段别名。对结果字段进行函数等处理时，建议使用字段别名封装，否则返回参数可能出现类似 sum(salary)这样的字符串作为返回参数名
注意：查询Oracle数据源时，若需查询其他用户中的表，按照 "user"."table" 格式填写，若不添加双引号，user、table将自动转化为为大写字母；查询Phoenix数据源时，若表中存在同名字段，须在字段前指明列簇，按照 "column family"."column" 格式填写。Phoenix SQL若不添加英文双引号，表名、列簇名、字段名将自动转换为大写字母。

WHERE条件中的参数为API请求参数。传参时需要将输入参数写为${传入参数名}的格式。

示例

select id, name, sum(salary) as sa
from t
where id = ${uid};    -- uid表示API的输入参数,用户在在线测试API和调用API时，看到的输入参数为uid。

DML模式

仅支持输入一条INSERT(不区分大小写)SQL语句；
示例
```
insert into t
(id,name)
values
```

API测试与返回结果

在配置API的最后一步，可对API进行测试，检查API返回结果。用户可填写入参的值，点击「开始测试」，在右侧查看返回结果，如下图所示：

API测试

返回结果是将JSON形式、CSV二维表形式将查询结果进行返回，对部分SQL类数据库可以展现执行此SQL的执行计划。

{
    "data": [
        {
            "name": "里斯",
            "id": "i004",
            "age": 20
        }
    ],
    "success": true,
    "errorCode": 1,
    "errorInfo": "成功",
    "header": {
        "content-length": "1899",
        "x-b3-parentspanid": "895d4581f6ef6a64",
        "x-forwarded-proto": "http",
        "api-token": "777F1C745E4FAC19604FB313D8508ABC8BFFA78B50D03039317A7FB1535CB888",
        "x-b3-sampled": "0",
        "x-forwarded-port": "80",
        "x-forwarded-for": "115.233.222.34, 116.62.227.70,172.16.20.15",
        "userid": "6380",
        "forwarded": "proto=http;host=api.your_host.com;for=\"172.16.20.15:36742\"",
        "accept": "*/*",
        "x-real-ip": "116.62.227.70",
        "invoketype": "pageTest",
        "x-forwarded-host": "api.your_host.com",
        "x-b3-traceid": "895d4581f6ef6a64",
        "x-b3-spanid": "46ed5e70de50a72b",
        "host": "172.16.20.16:8092",
        "content-type": "application/json",
        "apiid": "2147483647",
        "accept-encoding": "gzip,deflate",
        "user-agent": "Apache-HttpClient/4.4.1 (Java/1.8.0_144)"
    },
    "requestSQL": "select `id` as `id`,`name` as `name`,`age` as `age` from muyun_api_1 where `age` in (20) LIMIT 10 ",
    "jdbcQuerySpace": 12,
    "space": 113
}

将测试结果作为JSON样例保存：勾选该项后，最新的测试结果保存后以最新结果覆盖上次保存结果。

返回结果（JSON）中的内容说明如下：

data[] ：返回的数据，若未返回任何数据，则为空。
success ：调用状态（true/false）。
errorCode：返回状态码，对应的具体释义详见返回状态码。
errorInfo ：具体错误信息。
header ：若勾选了「返回结果携带 Request Header 参数」选项，则在返回结果中显示header中的常量参数相关内容。
requestSQL：本次查询的SQL文本，当查询结果有误，或出现性能问题时，便于用户根据SQL复现并定位问题。
jdbcQuerySpace：单位毫秒，本次查询的SQL在数据库内的耗时。
space ：单位毫秒，本次测试的完整的API调用耗时，利用space和jdbcQuerySpace两个时间的差异，当API返回耗时较长时，便于定位耗时的原因，是由平台造成的性能差或是API本身的查询耗时较长。

注册API

注册API的大部分参数与生成API相同，下面重点说明有差异的参数。

基本信息

所属类目：与生成API相同。
API名称：与生成API相同。
API中文名称：与生成API相同。
API描述：与生成API相同。
API path：在注册API的模式下，本参数是无效的。需在本页面的「API参数」中填写「后端服务Path」。
API标签：与生成API相同。
API市场分类：与生成API相同。

API参数

协议：除HTTP和HTTPS之外，还支持WebService和Socket两种。

HTTP/HTTPS协议，需填写如下内容：

后端Host、后端服务Path：二者共同组成注册API的前面部分，例如待注册的URL为 https://abc.com/s?id=1，则Host填写为https://abc.com，path填写为/s，后面的id作为入参，在Step2的API参数中填写。
请求方式：可支持POST、GET、PUT、DELETE、PATCH几种。
输入方式：
- 当请求方式选择为POST或PATCH时，可选择输入方式为JSON或Form表单。
- 当请求方式选择其他几种时，无需填写输入方式。

WebService协议：需填写如下内容：

后端Host、后端服务Path：与选择HTTP/HTTPS相同。
请求方式：不可选择。
输入方式：
- 可选择输入方式为JSON或Form表单。

Socket协议：需填写如下内容：

IP地址、端口：请求Socket接口的IP地址及端口
请求方式：不可选择。
输入方式：
- 可选择输入方式为JSON或Form表单。

各类协议的注册API，超时时间的设置与生成API相同。

注意

Form表单输入模式不支持传输加密

安全策略与限制

各参数与生成API相同。

注册API参数配置

默认值：参考生成API入参默认值。

注册API的输入参数支持从head/query/body中获取。

一般情况下:GET请求参数在query部分,post请求参数在body部分

若参数在返回结果的较深层级中，参数位置是query或者head时，可以通过“a.b.c”指定到嵌套格式深层级的参数值，字段类型选择string，例如：

原始API

配置方式

如果是输入参数是数组则可以通过字段值的多次输入实现，例如：

参数位置是body时，若输入方式是form-data也可通过“a.b.c”指定到嵌套格式的深层级的参数值，若输入方式是json则只能指定输入参数中第一层的参数，其下更深层级的字段则需要把嵌套内容作为完整入参内容输入，例如：

原始API

配置方式

常量参数

常量参数为后端所需要传递给第三方平台的默认参数,调用用户不可见.功能与默认值类似,用户未做填写时,后端会给第三方平台传输默认参数保证用户可完成注册.

高级配置
- 返回结果携带 Request Header 参数：若勾选此选项，在返回结果中将增加请求中header的信息，见本页的 API测试一节中的示例。
- 返回结果携带第三方API状态码：勾选后返回结果中将包含参数 “originalStatus”，用于显示第三方 API 返回的状态码信息。

NoSQL类API的配置

HBase

caution

HBase不支持行级权限控制
HBase仅支持向导模式配置，不支持脚本模式配置

用户需要选择读取的数据库类型、数据源和数据表，通过数据预览可查看当前选中数据表的字段和数据，便于快速排查选择的数据表是否正确。

字段预览：遍历前50行数据，显示所有的列簇和列，该数据预览仅供参考，以实际数据库中的数据为准。
数据预览：遍历前50行数据，部分数据为空表示该行无对应列簇/列。

HBase数据源配置_1

步骤二：输入参数与输出参数配置

用户点击“新增参数”后左框中显示的字段为遍历前50行数据获得的列簇和列。

手动添加其他参数：此处用于添加HBase元数据未获取到的字段，名称须与数据库完全匹配,列按照“列簇:列"的格式填写
操作符：HBase的操作符与其他数据源不同，使用需注意。
- Startrow:从输入的rowkey开始查找（包含输入）
- Endrow:查找到输入的rowkey之前停止（不包含输入）

//说明从Jim开始查找，直到查找到Tom前一行
scan 'scores', {COLUMN=>'course:english',STARTROW=>'Jim',ENDROW=>'Tom'}

Elasticsearch

caution

Elasticsearch类型的API不支持行级权限控制。
API查询Elasticsearch目前只支持JSON格式的DSL语句，因此仅支持脚本模式配置，不支持向导模式配置。
每个API仅支持单个DSL语句。

典型的查询语句如下：

{
  "query": 
        { "term":  { "id": ${_id} }}
}

query：DSL以query开头，用于指定查询条件。
term：类似SQL语句中的WHERE条件，WHERE条件中的参数为API请求参数。传参按照 "表中字段名”:${传入参数名}的格式填写，注意JSON中的标点符号均为英文字符。
其他Elasticsearch DSL语法可参考官方文档。

查询示例

假设Elasticsearch中的某个索引内容：

此时需要根据id作为输入参数查询信息，可在代码编辑栏输入如下DSL：

{
  "query": { 
    "bool": { 
      "must": [
        { "match": { "birthday":19270301}}
      ],
      "filter": [ 
        { "term":  { "id": ${_id} }},
        { "range": { "gender": { "gte" : 1} }} 
      ]
    }
  }
}

本DSL的查询逻辑：

birthday=19270301，并对结果值过滤。
过滤条件：
- id=入参id，API入参名称为_id,
- gender >= 1

返回结果

上述查询的返回结果示例如下（部分内容经过脱敏）：返回结果（data）中包含hits、_shards、took、timed_out4个key，hits包含返回的结果集，took表示在Elasticsearch端的查询耗时，详细的返回结果说明请参考官方文档。

{
    "data": {
        "_shards": {
            "total": 5,
            "failed": 0,
            "successful": 5,
            "skipped": 0
        },
        "hits": {
            "hits": [
                {
                    "_index": "api_cfrvpajt1",
                    "_type": "doc",
                    "_source": {
                        "birthday": "19270301",
                        "address": "四川省成都市都江堰市",
                        "gender": 1,
                        "create_time": "2022-05-30 17:00:23",
                        "idcard": "65420xxxxx",
                        "tel": "189xxxxxxxx",
                        "id": 4,
                        "email": "xxxx@263.net",
                        "username": "蒋xx"
                    },
                    "_id": "5",
                    "_score": 1.2039728
                }
            ],
            "total": 1,
            "max_score": 1.2039728
        },
        "took": 10,
        "timed_out": false
    },
    ……
}

MongoDB

caution

MongoDB类型的API不支持行级权限控制。
MongoDB类型的API不支持包含and、or等联合条件的查询。
API查询MongoDB仅支持脚本模式配置，不支持向导模式配置。
每个API仅支持单个查询语句。

danger

配置API时，需注意数据源所连接的默认数据库。若查询的表不在默认数据库时，点击下一步会报错：「SQL异常:数据库表不存在」。解决此问题，请在确认不影响其他API的前提下，可在数据源中心修改默认数据库。
若随意修改数据源中心的默认数据库，可能会造成连接此数据源的其他API报错。

典型的查询语句如下：

db.demo_set.find(
//通过 ${参数名} 指定查询条件，类似SQL语句中的where条件，作为API中的入参
    { user_id: ${uid}, 
        order_id: ${oid} },
        
//指定返回键，需返回时值为1，否则为0
    { sales_time: 1, 
        addr: 1, 
        value: 1 }
)

查询示例

假设MongoDB中存在的表信息如下：

demo_set表中存在4行数据，字段为id、name、age，其中包含2条完全重复的数据

> db.demo_set.find()
{ "_id" : ObjectId("62a479be71b5444001b72884"), "id" : "i1", "name" : "张三", "age" : 10 }
{ "_id" : ObjectId("62a479c371b5444001b72885"), "id" : "i2", "name" : "李四", "age" : 20 }
{ "_id" : ObjectId("62a479ca71b5444001b72886"), "id" : "i3", "name" : "王五", "age" : 30 }
{ "_id" : ObjectId("62a48d9471b5444001b72887"), "id" : "i1", "name" : "张三", "age" : 10 }

基于MongoDB的API进行排序查询，以及多函数带参执行（age>=20且按age排序），在代码编辑栏中输入如下查询条件：

db.demo_set.find(
  {"age": {$gte : ${age}}},
  {
    "id": 1,
    "name": 1,
    "age": 1
  }
).sort({"age": 1})

在配置入参时，需注意将入参 ${age}的类型设置为integer，否则将返回错误的查询结果。

返回结果

返回数据集在data中。

{
    "data": [
        {
            "count": 2
        },
        {
            "name": "李四",
            "_id": "62a479c371b5444001b72885",
            "id": "i2",
            "age": 20
        },
        {
            "name": "王五",
            "_id": "62a479ca71b5444001b72886",
            "id": "i3",
            "age": 30
        }
    ],
    ……
}

Redis

基于Redis配置的API，其配置过程与基础类型API类似，差异主要体现在以下几方面：

操作符：仅支持=、in、like。
不支持分页查询。
字段类型，可支持：string，hash，list，set、zset。
行级权限：当选择=或in操作符时，可支持行级权限，选择like操作符不支持行级权限。
入参固定只有1个，且入参名为key。
出参固定只有2个，key、value。

Solr

Solr数据源支持向导模式配置，不支持脚本模式配置。

创建

操作入口​

3种方式的差异与适用场景​

生成API​

基本信息​

API参数​

安全策略与限制​

向导模式参数​

脚本模式参数​

API测试与返回结果​

注册API​

基本信息​

API参数​

安全策略与限制​

注册API参数配置​

NoSQL类API的配置​

HBase​

Elasticsearch​

查询示例​

返回结果​

MongoDB​

查询示例​

返回结果​

Redis​

Solr​

操作入口

3种方式的差异与适用场景

生成API

基本信息

API参数

安全策略与限制

向导模式参数

脚本模式参数

API测试与返回结果

注册API

基本信息

API参数

安全策略与限制

注册API参数配置

NoSQL类API的配置

HBase

Elasticsearch

查询示例

返回结果

MongoDB

查询示例

返回结果

Redis

Solr