脚本数据模型

SuccBI提供了数据模型的脚本控制能力，对模型的查询、修改、调度都会执行到具体的脚本函数，可以由脚本函数来控制具体的逻辑。

启用脚本

在模型的属性设置>高级分类中，设置启用脚本属性，即可给模型附加脚本能力。
如果是脚本模型，创建一个新的空白模型并创建好最终的模型结构字段后，开启脚本即可编写脚本信息。

脚本模型示例地址：

1. 仪表板界面：天气展示可视化 (opens new window)
2. 脚本模型地址：天气模型 (opens new window)

脚本接口

/**
 * 脚本模型的脚本定义文件，主要用途如下：
 * 1. 为模型数据更新提供二次开发拓展点，此时需要设置模型物理表，模型操作体验与app模型相似，可通过onUpdateData和onUpdatedData拓展点实现更新前后的个性化二次开发。
 * 2. 个性化数据查询逻辑，通过onQueryData获取个性化数据，可以是一个db查询结果，也可以是爬取的远程数据。
 * 
 * 模型会根据物理表或onQueryData的结果自动生成对应字段，可在模型界面进一步编辑字段信息。
 */
import etl from "svr-api/etl";

/**
 * 返回脚本模型的数据查询结果。
 * 
 * 使用场景：
 * 1. 获取某个远程系统的restful api返回的json数据并返回，比如：从互联网服务器上获取实时的天气信息。
 * 2. 根据不同的查询参数选择查询不同的物理表
 * 
 * 需要注意：
 * 1. 在模型编辑界面，模型会根据输出结果自动生成物理表结构，用户可在字段列表界面编辑字段信息。
 * 
 * @param params 模型上设置的参数，仪表板或spg等通过数据集上的参数设置进行传递。
 * @returns 返回查询的数据，或者是对应的物理表或视图
 *  1. 返回一个二维数组，数组中的每列对应的用户要查询的列的数据（也许并不是模型的所有列，只是用户要查询的列）。
 *  2. 返回`DbTableInfo`其中ddl属性是一个sql，系统将使用这个sql作为查询的结果
 *  3. 返回`DbTableInfo`其中table属性是一个物理表或视图，系统将使用这个表作为查询的结果，系统会自动应用查询条件。
 *  4. 返回`void`，此时查询模型对应的物理表，系统会自动应用查询条件。
 *  5. 返回`QueryDataResultInfo`，返回的数据、字段、总行数完全由脚本定制。
 */
/*
function onQueryData(queryInfo: QueryInfo, params: JSONObject): DbTableInfo | any[][] | QueryDataResultInfo {
	return null;
}
*/

/**
 * 对查询结果进行再次处理的脚本扩展点。
 * 
 * 使用场景：
 * 1. 对查询结果中的一些隐私数据作加密或者隐藏，比如数据签名，需要调用第三方系统api来进行签名验证，并且在验证成功后将签名数据隐藏。
 * 
 * @param resultSet 查询的结果
 * @param queryInfo 当前查询的query
 * @returns 返回脚本处理后的查询结果，字段，总行数可以在脚本中进行修改。如果返回null，则表示不处理，查询将返回原始结果。
 */
/*
function onDidQueryData(resultSet: QueryDataResultInfo, queryInfo: QueryInfo): QueryDataResultInfo {
	return null;
}
*/

/**
 * 脚本模型数据更新时触发。
 * 使用场景：
 * 1. 脚本模型映射了物理表，需要在更新数据前做其他个性化处理，或调整数据包里的数据。
 * 2. 数据来自远程服务器，希望将更新数据提交到远程服务器。
 * @param data 
 * @param conn 与默认更新逻辑和onUpdatedData共用一个connection，支持在一个事务中处理所有逻辑。
 * @returns 显示返回false则不执行默认更新逻辑。需要注意的是阻断原有更新逻辑后，conn不会自动提交，需要在脚本中手动提交才会生效。
 */
function onUpdateData(data: CommonTableSubmitDataPackage, conn?: Connection): boolean {
	return true;
}

/**
 * 模型数据更新后触发。
 * @param data 
 * @param conn 与默认更新逻辑和onUpdateData共用一个connection，支持在一个事务中处理所有逻辑。
 */
function onDidUpdateData(data: CommonTableSubmitDataPackage, conn?: Connection): void {
	
}

/**
 * 模型调度时触发，用于处理一些模型调度中的个性化逻辑
 */
function onSchedule(): void {

}

/**
 * 模型调度对外提供的API支持。
 * 
 * @param dxcnl 通道信息
 * @param apiId 一个模型可以有多个api，外界可以指定调用的api
 * @param params 外部传递的参数，由脚本和外部调用者自己约定。
 * @param logs 日志对象，一个Map，可用于脚本向通道日志表里记录详细信息
 * @param progress 进度条对象，用于脚本自定义进度日志
 * @returns 
 */
// function onDXService(args: { dxcnl: DXChannelInfo, apiId: string, params: JSONObject, logs: any, progress: any }): DXResourceScriptAPIResult {
// 	return null;
// }

/**
 * 脚本可以主动报告自己有多少个API实现，便于前端界面选择使用。
 */
// function getDXServiceAPIDefineInfos(): Array<DXResourceScriptAPIInfo> {
// 	return null;
// }

/**
 * query编译拓展点，用于处理query查询中需要个性化处理的部分，返回的结果会代替原query继续解析查询。
 * 
 * 使用场景：
 * 1. 报表查询需要解析个性化过滤条件的需求，https://jira.succez.com/browse/CSTM-12384
 * @param query 
 * @return 返回null则表示无特殊处理
 */
function onCompileQuery(query: QueryInfo) : QueryInfo {
	return null;
}

/**
 * 同步数据拓展点，用于处理模型数据向es，redis等数据源同步数据时，个性化处理数据的需求。
 * 
 * @param row 当前行数据，作为当前拓展点计算的上下文
 * @param target 同步的目标数据源。
 * @returns 一次性将所有需要个性化处理的结果返回。
 */
function onSyncData(row: { [fieldName: string]: any }, target: "es"): { [fieldName: string]: any } {
	return null;
}