苍穹OpenAPI新体验之保存接口

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

苍穹OpenAPI新体验之保存接口

想知道如何在开放平台中维护保存服务接口的基本信息？

想知道如何定义保存接口的请求参数和返回参数？

想知道如何快速在线测试并发布API保存接口？

本期文章为你一一揭晓~

1 API保存服务接口简介

API2.0保存操作接口可根据不同入参，同时执行业务对象的保存、更新、批量保存和批量更新四种操作。其中，候选键作为接口执行更新逻辑的唯一主键，一般选择id或number/billno作为候选键，也可选择不同字段组合作为候选键，来实现个性化的接口需求。

2 API保存接口功能实现

以企业采购业务中的常见的采购订单为例，下面介绍如何在开放平台发布一个采购订单的保存接口。

步骤一：录入API基本信息

输入API编码、API名称、业务对象、操作方式、详细描述等信息，请求方式为“POST”，自动生成API请求地址。

录入API基本信息示例

步骤二：定义请求头部

系统已预置三个常用请求头参数，无需人工维护，其中参数“Idempotency-Key”为可选参数，主要用于防止接口重复调用。

定义请求头部示例

步骤三：定义请求体参数

点击“添加属性”按钮快速添加请求体参数，当业务对象含有多层级时（即包含分录和子分录），每个业务对象层级必须设有候选键。

候选键将作为保存数据时的校验依据，若在系统中查到相同候选键的数据，会执行“更新”操作，若没查到，则执行“保存”操作。请求入参必须按界面配置传参 。

定义请求体参数示例

其中参数示例会展示JSON、XML、SOAP1_1和SOAP1_2四种格式的入参结构。

四种格式的入参结构

步骤四：定义操作参数（非必选）

系统预置的保存参数，允许在保存时对数据进行一些特殊处理，如单据保存后自动提交等，这里不作详细介绍。

定义操作参数示例

步骤五：定义返回参数

保存操作服务的返回参数目前不允许用户自定义，统一按平台规范返回。API Response契约统一为:

{
       "data":{
              "failCount":"0",
              "result":[],
              "successCount":"0"
       },
       "errorCode":"",
       "message":null,
       "status":true
}

步骤六：在线调试API

点击“API测试”按钮，打开在线测试弹窗界面。获取页面URL，将请求体数据转换为JSON，展示在Request面板中。

点击“Send”按钮，后台模拟调用HTTP的POST请求访问服务，并将返回参数展示在页面的Response面板中。若需要测试批量新增或更新，直接在API测试界面修改请求Request即可。

1）在请求体中传入候选键“billno”，若未查找到相同编码的单据，系统执行新增操作（支持批量新增）。