自定义接口
本文档演示在氚云中编写自定义接口供第三方系统调用的方法。当 OpenAPI 接口无法满足需求时，可开发自定义接口。
编写自定义接口
新建表单用于编写自定义接口代码，该表单需至少包含一个控件方可保存。
在表单设计>后端代码插入自定义接口（默认代码保持不变，请勿删除）。保存成功后，即可使用该自定义接口。
以下示例在表单设计>后端代码中创建名为MyApiController的自定义接口类。自定义接口类必须继承H3.SmartForm.RestApiController类，所有方法逻辑入口统一为OnInvoke方法，通过actionName参数区分不同逻辑。
using System;
using System.Collections.Generic;
using System.Text;
using H3;
public class D00018sm493dffc8fb7849e0937dcb9eafdda0b9 : H3.SmartForm.SmartFormController
{
public D00018sm493dffc8fb7849e0937dcb9eafdda0b9(H3.SmartForm.SmartFormRequest request) : base(request)
{
}
protected override void OnLoad(H3.SmartForm.LoadSmartFormResponse response)
{
base.OnLoad(response);
}
protected override void OnSubmit(string actionName, H3.SmartForm.SmartFormPostValue postValue, H3.SmartForm.SubmitSmartFormResponse response)
{
base.OnSubmit(actionName, postValue, response);
}
}
//自定义接口代码放在本表单默认类代码下
//说明：自定义接口类个数无限制，类名可自定义但不可重复，必须继承自H3.SmartForm.RestApiController
public class MyApiController: H3.SmartForm.RestApiController
{
//此构造方法必须有，方法体内无需写代码
public MyApiController(H3.SmartForm.RestApiRequest request): base(request) { }
//第三方请求本自定义接口时触发本事件
protected override void OnInvoke(string actionName, H3.SmartForm.RestApiResponse response)
{
try
{
//“CreateOneData”可为任意非空字符串，用于判断第三方请求动作
/*注：actionName不能为以下已公开ActionName：
LoadBizObject 加载业务数据
LoadBizObjects 批量加载业务数据
CreateBizObject 创建业务数据
CreateBizObjects 批量创建业务数据
UpdateBizObject 更新业务数据
RemoveBizObject 删除业务数据
*/
if(actionName == "CreateOneData")
{
//从传入参数获取key为“para1”的值，未传则取默认值“defaultValue”，转换失败则报错
string stringValue = this.Request.GetValue<string>("para1", "defaultValue");
//从传入参数获取key为“para2”的值，未传则取默认值0，转换失败则报错
int intValue = this.Request.GetValue<int>("para2", 0);
//找到对应actionName时，回复key为“result”值为“success”的结果
response.ReturnData.Add("result", "success");
//找到对应actionName时，回复key为“message”值为空字符串的结果
response.ReturnData.Add("message", string.Empty);
//以下代码演示在自定义接口中查询业务对象，如无需请删除
H3.Data.Filter.Filter filter = new H3.Data.Filter.Filter();
H3.Data.Filter.And andMatcher = new H3.Data.Filter.And();
andMatcher.Add(new H3.Data.Filter.ItemMatcher("Status", H3.Data.ComparisonOperatorType.Equal, 1));//筛选数据状态为生效的数据
filter.Matcher = andMatcher;
H3.DataModel.BizObjectSchema schema = this.Request.Engine.BizObjectManager.GetPublishedSchema("D00021MyApiTest");
//查询“D00021MyApiTest”表单中符合筛选条件的业务对象
//注：H3.Organization.User.SystemUserId为系统默认用户Id，定时器或自定义接口中无当前登录人时使用
H3.DataModel.BizObject[] arr = H3.DataModel.BizObject.GetList(this.Request.Engine,
H3.Organization.User.SystemUserId,
schema,
H3.DataModel.GetListScopeType.GlobalAll,
filter);
Dictionary<string, object> dic = new Dictionary<string, object>();
//将第三方传入参数返回
dic.Add("StringValue", stringValue);
//返回小数
dic.Add("DoubleValue", 5.24343);
//将第三方传入参数返回
dic.Add("ArrayValue", new int[4]{ intValue, intValue + 1, intValue - 2, intValue + 3});
//回复key为“data”值为对象的结果
response.ReturnData.Add("data", dic);
}
else
{
//未找到actionName时，回复key为“result”值为“error”的结果
response.ReturnData.Add("result", "error");
//未找到actionName时，回复异常提示
response.ReturnData.Add("message", "无法处理actionName为“" + actionName + "”的请求！");
}
}
catch(Exception ex)
{
//代码异常时，回复key为“result”值为“error”的结果
response.ReturnData.Add("result", "error");
//代码异常时，回复捕获的异常原因
response.ReturnData.Add("message", ex.Message);
}
}
}
⚠️ 注意
actionName 不可使用以下保留字段：
- LoadBizObject
- LoadBizObjects
- CreateBizObject
- CreateBizObjects
- UpdateBizObject
- RemoveBizObject
第三方系统中调用自定义接口示例（C# 版）
string apiAddress = @"https://www.h3yun.com/OpenApi/Invoke";
System.Net.HttpWebRequest request = (System.Net.HttpWebRequest)System.Net.WebRequest.Create(apiAddress);
//设置请求方式为POST
request.Method = "POST";
//设置请求数据为json格式
request.ContentType = "application/json";
//身份认证参数，根据企业开发信息修改（注意：此两项请对管理员以外人员保密）
request.Headers.Add("EngineCode", "XXXXXXXXXXXX");//系统集成>企业开发信息>EngineCode
request.Headers.Add("EngineSecret", "XXXXXXXXXXXX");//系统集成>企业开发信息>Secret
//请求参数
Dictionary<string, object> dicParams = new Dictionary<string, object>();
//“CreateOneData”可为其他非空字符串，用于自定义接口判断请求动作
/*注：actionName不能为以下已公开ActionName：
LoadBizObject 加载业务数据
LoadBizObjects 批量加载业务数据
CreateBizObject 创建业务数据
CreateBizObjects 批量创建业务数据
UpdateBizObject 更新业务数据
RemoveBizObject 删除业务数据
*/
dicParams.Add("ActionName", "CreateOneData");
//“MyApiController”是自定义接口类名
dicParams.Add("Controller", "MyApiController");
//“D00021hca_test1”是自定义接口所在应用的应用编码
dicParams.Add("AppCode", "D00021hca_test1");
//查看应用编码方法：在`列表`页面点击左上角应用名后的`设置`按钮 > `重命名`，弹窗中显示应用编码
//传给自定义接口的字符串
dicParams.Add("para1", "传给接口的参数一");
//传给自定义接口的数值
dicParams.Add("para2", 999);
string jsonData = Newtonsoft.Json.JsonConvert.SerializeObject(dicParams);
byte[] bytes;
bytes = System.Text.Encoding.UTF8.GetBytes(jsonData);
request.ContentLength = bytes.Length;
using (System.IO.Stream writer = request.GetRequestStream())
{
writer.Write(bytes, 0, bytes.Length);
writer.Close();
}
string strValue = string.Empty;
using (System.Net.HttpWebResponse response = (System.Net.HttpWebResponse)request.GetResponse())
{
using (System.IO.Stream s = response.GetResponseStream())
{
string StrData = string.Empty;
using (System.IO.StreamReader Reader = new System.IO.StreamReader(s, Encoding.UTF8))
{
while ((StrData = Reader.ReadLine()) != null)
{
strValue += StrData + "\r\n";
}
}
}
}
⚠️ 注意
获取应用编码路径：列表> 点击左上角应用名后的设置按钮 >重命名
返回结果
| 参数 | 说明 |
|---|---|
| Successful | 接口调用是否成功（true/false） |
| ErrorMessage | 错误提示信息 |
| Logined | 保留字段，可忽略 |
| ReturnData | 接口返回的业务数据 |
| DataType | 返回数据类型（默认值 0） |
返回结果示例：
{
"Successful": true,
"ErrorMessage": null,
"Logined": false,
"ReturnData": {
"result": "success",
"message": "",
"data": {
"StringValue": "传给接口的参数一",
"DoubleValue": 5.24343,
"ArrayValue": [
999,
1000,
997,
1002
]
}
},
"DataType": 0
}
{
"Successful": true,
"ErrorMessage
}