11993-2019金蝶国际软件集团有限公司④内部公开请勿外传倪华珠2020年7月1993-2018金蝶国际软件集团有限公司金蝶云星空BOS专题中级课系统集成2Content010203WebAPI整体介绍常用接口说明案例演示常见问题及最佳实践04资料参考053Content010203常用接口说明案例演示常见问题及最佳实践04资料参考05WebAPI整体介绍4WebAPI介绍金蝶云星空WebAPI是一种轻量级的、可维护的、可伸缩的Web服务。采用HTTP+JSON，也就是用RESTful的方式来开发。使用.NETFramework4.0为开发平台，源代码使用C#编写。5WebAPI运行框架图星空Web服务层元数据业务服务自定义服务第三方系统调用开放1星空App服务层2接口服务调用服务调用服务接口服务1、星空提供了被集成的能力，将所有标准的操作封装成API，支持外部系统调用。2、星空的对外接口支持星空内置标准业务逻辑的处理，例如表单插件和应用服务插件等业务处理以及值更新、实体服务、缺省值等。3、开放的服务框架，支持自定义服务接口和原有服务接口的扩展开发6WebAPI权限控制7WebAPI日志管理8Content010203WebAPI整体介绍案例演示常见问题及最佳实践04资料参考05常用接口说明9常用接口说明-接口列表登录验证•用户名密码登录•第三方授权登录•域登录表单操作接口•保存•批量保存•暂存•提交•审核•反审核•下推•删除•查看•状态转换•分配•拆单•空操作查询接口•单据查询•元数据查询•分组查询其他接口•工作流快捷审批•分组保存•弹性域保存•发送消息10常用接口说明-服务地址名称服务地址登录http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.AuthService.ValidateUser.common.kdsvc保存http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Save.common.kdsvc批量保存http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.BatchSave.common.kdsvc暂存http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Draft.common.kdsvc提交http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Submit.common.kdsvc审核http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Audit.common.kdsvc反审核http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.UnAudit.common.kdsvc查看http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.View.common.kdsvc删除http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Delete.common.kdsvc单据查询http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.ExecuteBillQuery.common.kdsvc下推http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Push.common.kdsvc分配http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.Allocate.common.kdsvc弹性域保存http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.DynamicFormService.FlexSave.common.kdsvc登出http://ServerIp/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.AuthService.Logout.common.kdsvc11常用接口说明-登录接口传入参数列表参数含义备注acctID账套Id，从管理中心数据库查询获得参考查询：selectFDATACENTERIDfromT_BAS_DATACENTER必须username用户登陆名必须password密码必须lcid语言id,选择哪种语言访问，参考：中文2052，英文1033，繁体3076非必须，引用SDK组件辅助类调用则必须接口参数返回参数列表参数含义备注LoginResultType//激活Activation=-7,//云通行证未绑定Cloud账号EntryCloudUnBind=-6,//需要表单处理DealWithForm=-5,//登录警告Wanning=-4,//密码验证不通过（强制的）PWInvalid_Required=-3,//密码验证不通过（可选的）PWInvalid_Optional=-2,//登录失败Failure=-1,//用户或密码错误PWError=0,//登录成功管理员登陆可能出现返回-5的情况，这种情况在api验证时也可认为是允许的，具体可以根据实际情况来定。varresult=JObject.Parse(ret)["LoginResultType"].Value();if(result==1||result==-5){returntrue;}12常用接口说明-保存和批量保存接口13常用接口说明-保存和批量保存接口保存接口参数传入参数列表备注formid表单Id业务对象表单Id，字符串类型（必录）dataNeedUpDateFields需要更新的字段，数组类型，格式：[key1,key2,.]（非必录）注（更新单据体字段得加上单据体key）NeedReturnFields需返回结果的字段集合，数组类型，格式：[key,entitykey.key,.]（非必录）注（返回单据体字段格式：entitykey.key）IsDeleteEntry是否删除已存在的分录，布尔类型，默认true（非必录）SubSystemId表单所在的子系统内码，字符串类型（非必录）IsVerifyBaseDataField是否验证所有的基础资料有效性，布尔类，默认false（非必录）IsEntryBatchFill是否批量填充分录，默认true（非必录）ValidateFlag是否验证标志，布尔类型，默认true（非必录）NumberSearch是否用编码搜索基础资料，布尔类型，默认true（非必录）InterationFlags交互标志集合，字符串类型，分号分隔，格式："flag1;flag2;."（非必录）例如（允许负库存标识：STK_InvCheckResult）Model表单数据包，JSON类型（必录）主键赋值则为修改，没赋值则为新增14常用接口说明-保存和批量保存接口保存接口返回结果参数返回参数列表备注ResultResponseStatusIsSuccess是否保存成功Errors失败错误信息SuccessEntitys保存成功的实体信息SuccessMessages成功消息MsgCode消息代码Id单据内码Number单据编号NeedReturnData返回结果的字段集合15常用接口说明-保存和批量保存接口传入参数列表备注formid表单Id业务对象表单Id，字符串类型（必录）dataNeedUpDateFields需要更新的字段，数组类型，格式：[key1,key2,.]（非必录）注（更新单据体字段得加上单据体key）NeedReturnFields需返回结果的字段集合，数组类型，格式：[key,entitykey.key,.]（非必录）注（返回单据体字段格式：entitykey.key）IsDeleteEntry是否删除已存在的分录，布尔类型，默认true（非必录）SubSystemId表单所在的子系统内码，字符串类型（非必录）IsVerifyBaseDataField是否验证所有的基础资料有效性，布尔类，默认false（非必录）IsEntryBatchFill是否批量填充分录，默认true（非必录）ValidateFlag是否验证标志，布尔类型，默认true（非必录）NumberSearch是否用编码搜索基础资料，布尔类型，默认true（非必录）InterationFlags交互标志集合，字符串类型，分号分隔，格式："flag1;flag2;."（非必录）例如（允许负库存标识：STK_InvCheckResult）Model表单数据包，JSON类型（必录）主键赋值则为修改，没赋值则为新增BatchCount服务端开启的线程数，整型（非必录）注（数据包数应大于此值，否则无效）批量保存接口参数16常用接口说明-提交和审核接口17常用接口说明-提交和审核接口传入参数列表备注formid表单Id业务对象表单Id，字符串类型（必录）dataCreateOrgId创建者组织内码，字符串类型（非必录）Numbers单据编码集合，数组类型，格式：[No1,No2,.]（使用编码时必录）Ids单据内码集合，字符串类型，格式："Id1,Id2,."（使用内码时必录）SelectedPostId工作流发起员工岗位内码，整型（非必录）注（员工身兼多岗时不传参默认取第一个岗位）NetworkCtrl是否启用网控，布尔类型，默认false（非必录）提交接口参数返回参数列表备注ResultResponseStatusIsSuccess是否保存成功ErrorCode错误代码Errors失败错误信息SuccessEntitys保存成功的实体信息SuccessMessages成功消息MsgCode消息代码18常用接口说明-提交和审核接口审核接口参数传入参数列表备注formid表单Id业务对象表单Id，字符串类型（必录）dataCreateOrgId创建者组织内码，字符串类型（非必录）Numbers单据编码集合，数组类型，格式：[No1,No2,.]（使用编码时必录）Ids单据内码集合，字符串类型，格式："Id1,Id2,."（使用内码时必录）InterationFlags交互标志集合，字符串类型，分号分隔，格式："flag1;flag2;."（非必录）例如（允许负库存标识：STK_InvCheckResult）NetworkCtrl是否启用网控，布尔类型，默认false（非必录）返回参数列表备注ResultResponseStatusIsSuccess是否保存成功ErrorCode错误代码Errors失败错误信息SuccessEntitys保存成功的实体信息SuccessMessages成功消息MsgCode消息代码19常用接口说明-单据查询接口20常用接口说明-单据查询接口传入参数列表备注dataFormId业务对象表单Id，字符串类型（必录）FieldKeys需查询的字段key集合，字符串类型，格式："key1,key2,."（必录）注（查询单据体内码,需加单据体Key和下划线,如：FEntryKey_FEntryId）FilterString过滤条件，字符串类型（非必录）OrderString排序字段，字符串类型（非必录）TopRowCount返回总行数，整型（非必录）StartRow开始行索引，整型（非必录）Limit最大行数，整型，不能超过2000（非必录）查询接口参数返回值列表FValue1FValue2FValue3FValue4FValue5FValue621常用接口说明-自定义接口服务地址：http://ServerIp/K3Cloud/接口命名空间.接口实现类名.方法,组件名.common.kdsvc示例：http://192.168.66.60/k3cloud/ApiServiceTest.AAA.CustomBusinessService.ExecuteService,ApiServiceTest.AAA.common.kdsvc自定义接口必须继承Kingdee.BOS.WebApi.ServicesStub.AbstractWebApiBusinessService基类（基类需引用Kingdee.BOS.WebApi.ServicesStub.dll）22Content010203WebAPI整体介绍常用接口说明常见问题及最佳实践04资料参考05案例演示23案例演示1、调用登录接口登录。2、调用保存接口新增基础资料物料编码为“Test001”，名称为“测试001”。3、调用提交接口提交物料“测试001”。4、调用审核接口审核物料“测试001”。5、调用保存接口新增采购订单“CGDD00001”，分录选择物料“测试001”。6、调用保存接口修改采购订单单据头“变更原因”字段和单据体“采购数量”字段。7、调用单据查询接口查询采购订单“CGDD00001”的单据编码、采购组织、物料编码、采购数量8、自定义WebAPI接口查询采购订单执行明细表数据。24案例演示25Content010203WebAPI整体介绍常用接口说明案例演示04资料参考05常见问题及最佳实践261、客户端创建请求时，设置超时时间（5分钟）varrequest=(HttpWebRequest)HttpWebRequest.Create(uri);request.Timeout=300*1000;设置客户端和服务端通讯超时时间2、服务端修改设置超时时间web.config配置文件中27调用保存接口时，经常会遇到返回错误结果：某某基础字段是必填项，已经对此字段录入值了，依然报这个错误。常见原因有：1、此基础资料值不存在。比如对采购申请单的分录物料赋值“FMaterialId”:{“FNumber”:“0000”},但是此FNumber=0000的物料根本不存在，所以会提示字段“物料编码”是必填项。保存时基础资料字段必填项问题282、如果基础资料做了组织隔离，请求数据包中基础资料字段的使用组织字段的赋值顺序要先于此基础资料字段，并且此基础资料的使用组织无误。比如某单据的基础资料字段门店FBranchID的使用组织是FUseOrgId但是，FBranchID却先于FUseOrgId赋值，则会出现以下错误：保存时基础资料字段必填项问题293、基础资料字段是共享型，也即没做组织隔离，当对此基础资料以编码的方式赋值时，根据基础资料的编码可能会查到多个编码相同的基础资料，会默认使用第一个，但是保存检验器做了基础字段的业务组织校验的话，会返回此基础资料在某某业务组织下不存在，这种情况需要在表单插件重写BeforeSetItemValueByNumber事件，对Filter属性做基础字段的过滤条件进行赋值。保存时基础资料字段必填项问题304、对基础资料的使用组织的赋值时，要确定当前登录用户是否有这个组织的权限。5、没有设置组织隔离却传内码赋值的基础资料，例如编码规则。编码规则没有审核的操作，但是基础资料的默认是只查已审核非禁用的，根据内码和状态查不多该条记录，所以对编码规则的赋值不成功。需要对BeforeSetItemValueByNumber事件重写，对IsShowApproved和IsShowUsed赋值。6、基础资料的使用组织建议不要使用创建组织，因为创建组织默认使用上下文的组织，当数据包中没有对基础资料的使用组织赋值时，此基础资料在上下文的组织下如没有权限，则无法赋值成功。保存时基础资料字段必填项问题31调用WebAPI接口时，如果没有使用WebAPISDK组件，访问HTTPS服务地址时，需要加上安全协议类型。如果没有加上，则会报SSL/TLS安全通道创建失败。无引用SDK访问HTTPS正确的做法，请在调用WebAPI接口前，加上以下代码，注意客户端环境.netframwork需升级到4.0（不含）以上,以支持TLS1.2ServicePointManager.SecurityProtocol=(System.Net.SecurityProtocolType)SecurityProtocolTypeEnum.Ssl3|(System.Net.SecurityProtocolType)SecurityProtocolTypeEnum.Tls|(System.Net.SecurityProtocolType)SecurityProtocolTypeEnum.Tls11|(System.Net.SecurityProtocolType)SecurityProtocolTypeEnum.Tls12;32保存后提交审核保存单据后，进行提交、审核操作，正确的做法，请先调用保存接口，判断保存接口是否成功，成功则继续调用提交接口，判断提交是否成功，提交成功再去调用审核接口。不建议使用IsAutoSubmitAndAudit参数，此参数使用了大事务，而保存、提交、审核都有本身事务，会影响外围事务，造成事务终止异常。33示例：采购入库单CGRK00015，分录使用物料CH4446,物料启用了辅助属性YS、尺码、资产类别。值类型分别为辅助资料、手工输入、基础资料，查询此采购入库单的辅助属性YS、尺码、资产类别的值。查询辅助属性字段341、通过查看接口查询采购入库单CGRK00015的辅助属性内码为10050，固定列FF100001、FF100002、FF100501分别对应YS、尺码、资产类别查询辅助属性字段352、通过单据查询接口对辅助属性的标识FAuxPropId结合固定列FF100001、FF100002、FF100501，输入FieldKeys的值FAuxPropId.FF100001.FDataValue,FAuxPropId.FF100002,FAuxPropId.FF100501.Fname,采购入库单的编码作为过滤条件，查询结果如下：查询辅助属性字段36示例：采购入库单CGRK00015，分录使用物料CH4446,物料启用了仓位。1、通过单据查看结果，查找到仓位字段FStockLocId信息截图如下：查询仓位信息372、通过单据查询接口，输入“FStockLocId.FF100001.FName,FStockLocId.FF100002.Fname”做为FieldKeys的值，以单据编号作为过滤条件，结果截图如下：查询仓位信息38示例：凭证号为1的凭证，核算维度字段绑定的值类型是供应商和部门这两种基础资料。1、通过查看两种类型对应的FFlex4、FFlex5列。查询核算维度字段信息392、通过单据查询接口，输入“FDetailID.FFlex4.FNumber,FDetailID.FFlex4.FName,FDetailID.FFlex5.FNumber,FDetailID.FFlex5.FName”做为FieldKeys的值，以凭证号作为过滤条件，查询结果如下：查询核算维度字段信息40示例：采购申请单的“申请类型”字段做查询演示，单据编号为CGSQ050049的采购订单的申请类型的名称。如何查询单据下拉列表某一项的标题411、先通过单据查询接口查询采购申请单编码为CGSQ050049的申请类型字段，得到申请类型的枚举是Material，结果如下：如何查询单据下拉列表某一项的标题422、在BOS设计器中，打开采购申请单元数据XML文件，通过申请类型字段的标识，查找到它的枚举类型，通过元数据查询得到申请类型字段的EnumType为1fb62996-71ba-47ec-9e48-b766092962ba，结果如下：如何查询单据下拉列表某一项的标题433、在WebAPI单据查询接口界面，查询枚举单据（FormId=BOS_EnumBill），以第一步查询的结果作为FValue的值，以第二步查询的结果做为FID的值，去做过滤条件，则查出最终结果，从结果可以看出，单据编号为CGSQ050049的采购申请单的申请类型字段的枚举名称为“物料”如何查询单据下拉列表某一项的标题44最佳实践-不要每次调用接口都登录错误正确45最佳实践-不要在循环里面调用接口错误正确46通过WebAPI处理海量数据问题，以单据查询接口查询采购订单为例，测试采购订单80万单据，用三种方式去测试：无并行单客户、单客户并行、多客户并行最佳实践-通过接口如何高效查询大数据47最佳实践-通过接口如何高效查询大数据经测试，无并行单客户方式耗时70秒；单客户并行方式，耗时为20秒；多客户并行方式，耗时12秒。当然，并行是依赖于客户端的CPU核数，对客户端的硬件设备要求高。综上所述，如果需要保证调用接口高效，并且客户端CPU足够强大的情况下，推荐多客户并行方式48批量保存接口，通过参数BatchCount启动多线程方式，使同步单据效率大大提升。但是并不是启动线程越多越好，这要取决于服务器的硬件设备处理能力，可以结合服务器的硬件设备处理能力进行测试调优，设置最合适的BatchCount值。最佳实践-通过接口如何高效保存大数据49在第三方集成过程中，可能会遇到各种问题，推荐使用Postman调试工具，Postman是一个Chrome扩展，提供功能强大的WebAPI&HTTP请求调试。推荐使用Fiddler等抓包工具，监控请求和响应的情况。使用工具进行监控定位问题50Content010203WebAPI整体介绍常用接口说明案例演示04常见问题及最佳实践05资料参考51资料参考.netK/3CloudWebAPI集成开发客户端不引用组件示例【分享】http://club.kisdee.com/forum.php?mod=viewthread&tid=939582JavaK/3CloudWebAPI销售订单Java完整示例【分享】http://club.kisdee.com/forum.php?mod=viewthread&tid=959863phpK/3CloudWebAPI销售出库单PHP完整示例【分享】http://club.kisdee.com/forum.php?mod=viewthread&tid=986575WebApi之新接口推广http://club.kisdee.com/forum.php?mod=viewthread&tid=752737K/3CloudWebAPI接口说明文档http://club.kisdee.com/forum.php?mod=viewthread&tid=71466252资料参考WebAPI【财务凭证】核算维度赋值【分享】http://club.kisdee.com/forum.php?mod=viewthread&tid=989427WebAPI查询表单数据接口示例http://club.kisdee.com/home.php?mod=space&uid=421001&do=blog&id=119707WebAPI批量保存接口示例http://club.kisdee.com/home.php?mod=space&uid=421001&do=blog&id=119714小技巧-如何逐步构建采购订单WebAPI保存接口参数http://club.kisdee.com/forum.php?mod=viewthread&tid=992078K3Cloud系统集成实现下推单据转换调用【分享】http://club.kisdee.com/forum.php?mod=viewthread&tid=763172K/3CloudWebAPI调用任意操作实现方案【分享】http://club.kisdee.com/forum.php?mod=viewthread&tid=99420953答疑时间答疑54Thanksterimakasih感謝谢谢ありがとうขอบคุ ณ1993-2019金蝶国际软件集团有限公司
