操作API介绍

栏目：云苍穹知识作者：金蝶来源：金蝶云社区发布：2024-09-23浏览：1

操作API介绍

变更记录

产品版本	更新内容	更新日期
V5.0.011	初始版本	2022年6月
V6.0.1	应用开放平台更名为OpenAPI，迁移至开放服务云	2023年10月

1. 简介

1.1 功能介绍

操作API是将金蝶云苍穹业务对象如单据、基础资料的操作（查询，保存，提交等），通过零代码配置的模式，一键发布成为OpenAPI，系统自动生成服务接口及服务契约。

OpenAPI采用扁平化的出入参结构，更符合Restful规范。同时，接口的请求参数和返回参数，会严格遵循页面配置，对API逻辑产生约束。另外，路由中增加了ISV标识，用于区分标准和二开的API。

1.2 应用场景

发布苍穹标准API供外部第三方应用调用；
预置标准接API，提供给苍穹平台其他模块调用。

1.3 系统路径

【开放服务云】-【OpenAPI】→【API管理】→【API开发】

1.4 字段说明

1）当请求方式为GET时

字段名称	详细解释
API基本信息
API编码	手工录入，建议创建有实际业务语义的编码
API名称	手工录入，建议创建有实际业务语义的名称
请求方式	API请求方法，支持GET/POST
业务对象	操作服务的业务对象
所属应用	业务对象所属应用
分组	接口所属分组
操作方式	业务对象的操作，如查询、保存等
使用状态	API使用状态共有四种。内测：接口仍在内部测试中；发布：正式对外开放；维护：API将来会被废弃，不推荐使用；禁用：禁止使用。
适用版本号	依赖的实体对象对应的苍穹最低版本号
接口类型	同步
请求地址	请求url地址，自动生成格式为：/kapi/v2/{isv}/{appId}/{formId}/{serviceName} {isv}：开发商标识，金蝶标准接口的开发商标识为空 {appid}：业务对象所属的应用编码 {formId}：业务对象编码 {serviceName}：输入的API编码
完整服务地址	接口完整请求地址
详细描述	API详细描述及功能场景用途
配置项
第三方应用授权	开关打开，代表该API不允许通过cookies、匿名等非第三方应用认证的方式访问
出参仅返回Data域	出参仅返回Data域（不包括Status）
返回动态对象	【仅查询操作展示】开启后返回DynamicObject 的序列化数据，可通过反序列将其还原为DynamicObject对象
启用查询权限控制	【仅查询操作展示】启用后，会校验当前调用接口用户的组织权限和数据规则，避免查询到用户权限范围外的数据
是否脱敏	开关打开，代表该API需要脱敏，关闭则不需要脱敏
防止重复请求	开启防止重复请求时，相同请求参数的请求在30秒内只能调用一次
返回多语言	【仅查询操作展示】开启开关后，若返回参数为多语言字段，则返回该字段存在的所有语言值
WebService信息
命名空间	Webservice接口的命名空间，建议以http或https开头
输入参数名	输入参数名
输出参数名	输入参数名
WSDL方法名	WSDL方法名
请求头部
参数名称	请求头参数名称，系统已默认预置content_type和access_token，无需重复添加
参数值	请求头参数值
说明	请求头参数说明
Query参数
参数名称	Query参数名称，即请求的入参。即可以从业务对象中添加，也可以手工添加，允许修改参数名称。
对象属性	若从业务对象中添加，则为添加的实体属性编码；若是手工添加的参数，则和参数名称保持一致。不允许修改
参数类型	Query参数类型
必填	定义查询类API服务的Query参数，在调用时是否必传
默认值	请求参数默认值
说明	Query参数说明
层级	参数在业务对象中所在层级，如：若参数为分录中的参数，则层级为2
示例	Query参数示例，根据选择的参数自动带出
查询条件
左括号	当查询条件有多个时，可以添加括号组合查询，如查询条件为（A or B）and C
条件字段	只允许从业务对象中选择，条件字段用于和用户传入的Query参数进行比较，用来过滤查询指定的数据，如createtime（条件字段）大于 time（query参数）、billstatus （条件字段）等于 status（query参数）
字段类型	根据条件字段自动带出
字段描述	根据条件字段自动带出
比较方式	支持14种比较方式：等于、不等于、在...中、不在...中、为空、不为空、包含、不包含、以...开始、以...结束、大于、小于、大于等于、小于等于。
比较变量	与条件字段作比较变量名称，来源于query参数
右括号	当查询条件有多个时，可以添加括号组合查询，如查询条件为(A or B) and C
逻辑连接符	与/或，用于组合不同的查询条件
排序
排序字段	只允许从业务对象中选择，用于控制返回参数的排序，用法同order by。
字段描述	根据排序字段自动带出
排序方式	顺序/倒序
返回参数
参数名称	返回参数名称，组装在返回信息的data中，只能从业务对象中添加，允许修改参数名称
对象属性	添加的实体属性编码，不允许修改
参数类型	返回参数类型
说明	返回参数说明
层级	参数在业务对象中所在层级，如：若参数为分录中的参数，则层级为2
示例	返回参数示例，根据选择的参数自动带出
错误码
错误码	API错误码
描述	错误码描述

2）当请求方式为POST时

字段名称	详细解释
API基本信息	字段与get请求一致
请求头部	字段与get请求一致
请求体
参数名称	请求体参数名称，即请求的入参。即可以从业务对象中添加，也可以手工添加，允许修改参数名称
对象属性	若从业务对象中添加，则为添加的实体属性编码；若是手工添加的参数，则和参数名称保持一致。不允许修改。
参数类型	请求体参数类型
必填	定义请求体参数，在调用时是否必传
默认值	请求参数默认值
说明	请求体参数说明
层级	参数在业务对象中所在层级，如：若参数为分录中的参数，则层级为2
示例	请求体参数示例，根据选择的参数自动带出
查询条件	当操作方式为保存（save）时隐藏
左括号	当查询条件有多个时，可以添加括号组合查询，如查询条件为（A or B）and C
条件字段	只允许从业务对象中选择，条件字段用于和用户传入的请求体参数进行比较，用来过滤查询指定的数据，如createtime（条件字段）大于 time（请求体参数）、billstatus （条件字段）等于 status（请求体参数）
字段类型	根据条件字段自动带出
字段描述	根据条件字段自动带出
比较方式	支持14种比较方式：等于、不等于、在...中、不在...中、为空、不为空、包含、不包含、以...开始、以...结束、大于、小于、大于等于、小于等于。
比较变量	与条件字段作比较变量名称，来源于请求体参数
右括号	当查询条件有多个时，可以添加括号组合查询，如查询条件为(A or B) and C
逻辑连接符	与/或，用于组合不同的查询条件
排序	仅当操作方式为查询（query）时展示，字段与get请求一致
保存参数	仅当操作方式为保存（save）时展示
参数项	特殊保存功能参数
说明	参数说明
值	参数值
返回参数
参数名称	返回参数名称，即请求的出参
参数类型	返回参数类型
说明	返回参数说明
示例	返回参数示例
错误码	字段与get请求一致

1.5 按钮说明

按钮名称	详细解释
单据头
保存	保存当前API服务信息
API测试	打开API在线测试弹窗界面
退出	退出当前界面
请求头
增行	列表新增空白行
删行	点击按钮，删除勾选行数据，支持多条数据批量删除
上移	勾选请求头数据，点击按钮，行数据会上移一行
下移	勾选请求头数据，点击按钮，行数据会下移一行
参数示例	弹出请求参数示例弹窗
Query参数/请求体
添加属性	弹出对象选择弹窗，支持批量勾选，点击确定后会自动填充数据到query参数/请求体列表中
参数示例	弹出请求参数示例弹窗
增行	列表新增空白行
删行	点击按钮，删除勾选行数据，支持多条数据批量删除
上移	勾选行数据，点击按钮，行数据会上移一行
下移	勾选行数据，点击按钮，行数据会下移一行
填充示例数据	适用保存操作API，开始填充请求参数示例
查询条件
增行	列表新增空白行
删行	点击按钮，删除勾选行数据，支持多条数据批量删除
插入	点击按钮，插入空白行
预览	点击按钮，弹出查询API服务的过滤条件预览弹窗
排序
增行	列表新增空白行
删行	点击按钮，删除勾选行数据，支持多条数据批量删除
上移	勾选行数据，点击按钮，行数据会上移一行
下移	勾选行数据，点击按钮，行数据会下移一行
返回参数
添加属性	点击按钮，弹出对象选择弹窗，支持批量勾选，点击确定后会自动填充数据到返回参数列表中。注意：若选择分录或子分录中的字段，必须选择分录标识
参数示例	点击按钮，弹出返回参数示例弹窗
删行	点击按钮，删除勾选行数据，支持多条数据批量删除
上移	勾选行数据，点击按钮，行数据会上移一行
下移	勾选行数据，点击按钮，行数据会下移一行
错误码
增行	列表新增空白行
删行	点击按钮，删除勾选行数据，支持多条数据批量删除

2. 主要操作

2.1 打开API服务管理列表

打开API管理列表，在左树通过切换云可以展示该不同业务云下的API服务，默认按最近修改时间倒序展示接口信息。

2.2 维护API服务

点击新增按钮，新增操作API，当请求方式为GET时，只能创建查询操作服务；当请求方式为POST时，可以创建查询、保存、删除、提交、审核等操作服务。

操作步骤（以get查询接口为例）：

1）录入API基本信息：API编码、API名称、业务对象、操作方式、详细描述，API请求地址自动生成。

2）定义请求头部：即定义请求头参数（header），操作服务无需维护，系统已预置了content_type(内容类型）和accesstoken（请求令牌）两个参数。

3）定义query参数：即定义请求的入参，这些参数会作为查询条件的比较变量，界面设置参数类型和是否必填。支持手工添加或点击“添加属性”按钮快速添加参数。请求入参必须按界面配置传参。

注意：当query参数非必填时，必须配置默认值。若用户不传某个查询参数时，希望自动忽略该参数对应的查询条件，应将参数设为非必填，默认值设为"*"。

4）定义查询条件：即定义查询类请求的过滤条件，将业务对象中的字段和传入参数（比较变量）进行比较，来过滤筛选指定的数据。目前共支持等于、大于、包含等共14种比较方式。可以使用单个条件或通过逻辑连接符进行组合查询。点击条件字段后的图标，可展示该业务对象的属性参数（含关联的基础资料）。

勾选后点击确定，并和Query参数进行比较生成查询条件。点击预览按钮可查看具体的查询过滤逻辑。

备注：当查询条件中比较方式有选择“在...中”或“不在...中”时，对应的比较变量的参数类型必须为Array数组类型。系统预置了Array<Integer>、Array<String>、Array<Long>、Array<Date>四种参数类型供选择。

5）定义排序（可选）：用户可在界面定义返回参数展示的排序方式，即orderby排序表达式，点击排序字段后的图标，选择字段进行排序，可定义顺序或倒序，同时支持组合排序。

6）定义返回参数：即定义请求的出参，目前仅支持从业务对象中选择需要返回的参数数据，暂不允许用户完全自定义新增返回参数。点击“添加属性”按钮，勾选需要返回的参数，确认后点击“保存”按钮，API维护完成。

API Response契约统一为:
{

“data { } //结果数据

“errorCode”: “”, //错误码
“message”: null, //失败时的提示信息

“status”: true/false //是否成功

}

查询操作API的返回参数会自动组装在接口返回信息的data域中。

2.3 在线测试

新建的API服务默认状态为内测，代表接口仍在内测阶段，接口开发人员需要通过充足的测试验证之后才允许发布。开放平台在系统中内置了在线测试功能，允许用户在系统内通过调整维护的参数及示例，无需获取token即可进行快捷方便的接口调试。

1) 点击“API测试”按钮，打开在线测试弹窗界面。系统获取API维护页面传递的请求地址，并自动拼接成访问URL。同时根据API维护页面传递的请求方式自动渲染页面为GET请求，拼接条件到URL并允许编辑，参数页面默认隐藏。（若为POST请求，则会获取页面URL数据以及请求体数据转换为json，并展示在参数页面中。）

2) 点击“send”按钮，后台模拟调用HTTP的GET请求访问服务，并将返回结果格式化渲染到页面Respones容器的编辑器中展示。遇到异常返回，会将全部返回值渲染到result页，将错误信息格式化渲染到stack页中。

3) 由于该操作会影响数据库真实数据（如增删改等API 服务），禁止在生产环境测试！