1993-2022金蝶国际软件集团有限公司④内部公开请勿外传开放平台—自定义API开发金蝶云·苍穹开放平台服务部吕传勇2022.12.122④内部公开请勿外传0203概览1-1使用场景及特点2-1注解概览|2-2注解说明|2-3使用示例|2-4页面操作|2-5高阶用法3-1基础用法|3-2高阶用法|3-3注意事项04Java插件开发脚本开发开发演示目录01013概览1-1使用场景及特点④内部公开请勿外传4使用场景及特点使用特点：•Java插件：系统自动解析出入参数，快速方便地生成自定义API，能满足一切场景需要。•脚本开发：可实现多个API、微服务、函数库等之间的组合调用，即开即用，免于部署。自定义API用于拓展平台的API能力，满足一些个性化的需求，这类API不依附任何业务对象，出入参数可以完全自定义。目前开放平台支持Java插件、脚本开发两种方式自定义API。025Java插件开发2-1注解概览2-2注解说明2-3使用示例2-4页面操作2-5高阶用法④内部公开请勿外传6注解概览开放平台提供以下5种类型的Java注解，开发者需在开发时使用对应注解，以便开放平台能识别API并解析出入参。注解所在包路径kd.bos.openapi.common.custom.annotation支持HibernateValidator注解校验及自定义校验注解注解类ApiControllerApiMappingApiHeadersApiErrorCodes方法注解ApiPostMappingApiGetMappingApiHeadersApiErrorCodes方法参数注解ApiParamApiRequestBody方法返回值注解ApiResponseBodyModel模型注解ApiModelApiParam④内部公开请勿外传7注解说明④内部公开请勿外传8注解说明详细说明：https://dev.kingdee.com/index/open/detail/sdk/1565335175934512128④内部公开请勿外传9使用示例—类注解类实现java.io.Serializable序列化类标记ApiController注解@ApiController(value="open",desc="用户example")publicclassExampleControllerimplementsSerializable{privatestaticfinallongserialVersionUID=-12768624606278856L;}@ApiController(value="open",desc="用户example")@ApiMapping("/example")@ApiHeaders({@ApiHeader(name="a",desc="aa",example="aaa"),@ApiHeader(name="b",desc="bb",example="bbb")})@ApiErrorCodes({@ApiErrorCode(code="001",desc="0001"),@ApiErrorCode(code="002",desc="0002")})publicclassExampleControllerimplementsSerializable{privatestaticfinallongserialVersionUID=-12768624606278856L;}④内部公开请勿外传10使用示例—方法注解（GET请求）方法标记ApiGetMapping注解方法参数为基本类型方法参数标记ApiParam方法返回结果必须为CustomApiResult@ApiGetMapping(value=“/demo1”,desc=“get请求”)publicCustomApiResultdemo1(@ApiParam("i参数")Integeri){//TODOreturnCustomApiResult.success("");}@ApiGetMapping(value="/demo1",desc="get请求")@ApiHeaders({@ApiHeader(name="c",desc="cc",example="ccc"),@ApiHeader(name="d",desc="dd",example="ddd"),})@ApiErrorCodes({@ApiErrorCode(code="003",desc="0003"),@ApiErrorCode(code="004",desc="0004")})publicCustomApiResult<@ApiResponseBody("结果")String>demo1(@Valid@Min(3)@ApiParam("i参数")Integeri){//TODOreturnCustomApiResult.success("");}④内部公开请勿外传11使用示例—方法注解（POST请求）方法标记ApiPostMapping注解方法参数标记ApiParam或ApiRequestBody注解方法返回结果必须为CustomApiResult@ApiPostMapping("/save")publicCustomApiResultsave(@ApiParam("用户信息")ExampleModel1e){//TODOreturnCustomApiResult.success(1);}@ApiPostMapping("/save")@Validated@ApiHeaders({@ApiHeader(name="e",desc="ee",example="eee"),@ApiHeader(name="f",desc="ff",example="fff"),})@ApiErrorCodes({@ApiErrorCode(code="005",desc="0005"),@ApiErrorCode(code="006",desc="0006")})publicCustomApiResultsave(@Valid@NotNull@ApiParam("用户信息")ExampleModel1e){//TODOreturnCustomApiResult.success(1);}④内部公开请勿外传12使用示例—方法注解（POST请求）ApiParam注解适用于任何参数类型，无限制要求ApiRequestBody注解适用于方法参数为Map或Model类型，且方法只能有一个参数一个方法的参数只能用ApiParam和ApiRequestBody其一标记，二者不能同时存在于一个方法参数中@ApiPostMapping("/save")publicCustomApiResultsave(@ApiParam("用户信息")ExampleModel1e){//TODOreturnCustomApiResult.success(1);}@ApiPostMapping("/save")publicCustomApiResultsave(@ApiRequestBody("用户信息")ExampleModel1e){//TODOreturnCustomApiResult.success(1);}{"userId":"1670896097829","userName":"echtQ","account":"AEpNO","password":"jwqGb","httpMethod":"POST"}{"e":{"userId":"1670896097829","userName":"echtQ","account":"AEpNO","password":"jwqGb","httpMethod":"POST"}}④内部公开请勿外传13使用示例—Model参数注解详细说明：https://dev.kingdee.com/index/open/detail/sdk/1565335176303610880类实现java.io.Serializable序列化类标记ApiModel注解属性字段标记ApiParam注解@ApiModelpublicclassExampleModel1implementsSerializable{privatestaticfinallongserialVersionUID=-506072859L;@ApiParam("用户ID")privateLonguserId;@ApiParam("用户名")privateStringuserName;@ApiParam("账号")privateStringaccount;@ApiParam("密码")privateStringpassword;//省略get/set}@ApiModelpublicclassExampleModel1implementsSerializable{privatestaticfinallongserialVersionUID=-506072859L;@ApiParam("用户ID")@Min(value=10000000L)privateLonguserId;@ApiParam("用户名")@NotNull@Length(min=2,max=10)privateStringuserName;@ApiParam("账号")@NotNull@Length(min=6,max=20)privateStringaccount;@ApiParam("密码")@NotNull@Length(min=6,max=20)privateStringpassword;//省略get/set}④内部公开请勿外传14页面操作—API登记详细说明：https://vip.kingdee.com/knowledge/specialDetail/226337046514476288?category=358247193897143040&id=294499338368404736&productLineId=29通过Java插件开发完API后，在开放平台通过简单的接口配置后，系统自动解析出入参数，快速方便完成自定义API登记菜单路径：开发服务云-开放平台-API管理 所属应用插件类所属的应用，通过所属应用路由来查找插件 类名设置了@ApiController注解的Controller插件类 方法名Controller类下标记@ApiGetMapping或@ApiPostMapping注解的方法名注意事项方法完整URL地址：v2+所属应用+类的ApiMapping值（如果有）+方法的ApiGetMapping/ApiPostMapping值④内部公开请勿外传15高阶用法自定义API开发：https://dev.kingdee.com/index/open/detail/sdk/1565335175934512128自定义API案例：https://dev.kingdee.com/index/open/detail/sdk/1565335176303610880自定义API传输TextPlain：https://dev.kingdee.com/index/open/detail/sdk/1565335177016642560请求头及响应头处理：https://dev.kingdee.com/index/open/detail/sdk/1565335177368964096异常及状态码：https://dev.kingdee.com/index/open/detail/sdk/1565335177838726144文件流处理接口：https://dev.kingdee.com/index/open/detail/sdk/15653351781910476800316脚本开发3-1基础用法3-2高阶用法3-3注意事项④内部公开请勿外传17基础用法在开放平台维护API的基本信息、请求参数、返回参数等信息API脚本模块使用脚本编写业务逻辑菜单路径：开发服务云-开放平台-API管理④内部公开请勿外传18基础用法—使用引用资源使用场景：需要对其他API进行组合调用形成新的API的场景使用步骤：①在开放平台维护API的基本信息、请求参数、返回参数等信息②引用资源选择需要调用的API③API脚本中通过引用资源别名来调用详细说明：https://vip.kingdee.com/knowledge/specialDetail/226337046514476288?category=358247193897143040&id=322686880653270784&productLineId=29④内部公开请勿外传19脚本帮助手册提供脚本语法说明及实例常用功能伪代码模板菜单路径：开发服务云-开放平台–其他–帮助手册/代码片段管理④内部公开请勿外传20高阶用法自定义脚本开发案例：https://dev.kingdee.com/index/open/detail/sdk/1565335178996354048自定义API（脚本开发）：https://vip.kingdee.com/knowledge/specialDetail/226337046514476288?category=358247193897143040&id=322686880653270784&productLineId=29④内部公开请勿外传21注意事项API作为引用资源被调用时，参数格式为对应API的请求参数格式。只有GET请求需要将参数转为Map结构进行传参。举例：https://127.0.0.1/ierp/kapi/v2/mal/mal_order/cancel?billno=KmoOR{"billno":"KmoOR"}若是GET请求的查询操作API需要按照POST请求的查询格式传参，将非pageSize和pageNo放在data参数中。举例：https://127.0.0.1/ierp/kapi/v2/base/bos_org_pattern/getList?id=72&id=56&pageSize=10&pageNo=1{"data":{"id":[72,56]},"pageSize":10,"pageNo":1}0422开发演示Java插件/脚本开发API实操演示1993-2022金蝶国际软件集团有限公司④内部公开请勿外传特别声明ClaimofConfidential本文件内容为④内部公开请勿外传：禁止未授权的内部、第三方人员使用与访问非专项必要的业务与项目负责人，收到此内容请立即删除严禁在未经过主管领导审批，发送给无关业务团队与人员特别声明ClaimofConfidential•1993-2022金蝶国际软件集团有限公司。保留一切权利。•未经金蝶国际软件集团有限公司的书面许可，任何单位或个人不得以任何形式或为任何目的复制或传播本文档的任何内容。本文档中包含的信息如有更改，恕不另行通知。•本文档提到的金蝶®、金蝶云®、金蝶云EBC®、金蝶云苍穹®、金蝶云星瀚®、金蝶云星空®、金蝶云星辰®、金蝶KIS®、K/3®、金蝶EAS®、友商网®、Apusic®和其它金蝶产品和服务以及它们各自的徽标均为金蝶软件（中国）有限公司或其关联公司在中国和其他国家或地区的商标或注册商标。本文档提到的所有其它产品和服务名称分别为它们各自公司的商标。•本文档所用数据均为虚构的模拟数据，不代表任何一家企业的真实情况，如有权利人认为文档中的任何内容存在侵权情况，请反馈给金蝶官方邮箱（DataSubjectRequest@kingdee.com），我们将在15个工作日内处理。•注：①②机密信息严禁泄露③秘密信息严禁泄露④内部公开请勿外传
