脚本数据模型

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 queryArgs 发起查询的请求参数
 * @param params 模型上设置的参数，仪表板或spg等通过数据集上的参数设置进行传递。
 * @returns 返回查询的数据，或者是对应的物理表或视图
 *  1. 返回一个二维数组，数组中的每列对应的用户要查询的列的数据（也许并不是模型的所有列，只是用户要查询的列）。
 *  2. 返回`DbDataSourceInfo`时，系统将使用其中的sql属性作为查询的结果
 *  3. 返回`DbDataSourceInfo`其中tableName属性是一个物理表或视图，系统将使用这个表作为查询的结果，系统会自动应用查询条件。
 *  4. 返回`void`，此时查询模型对应的物理表，系统会自动应用查询条件。
 *  5. 返回`QueryDataResultInfo`，返回的数据、字段、总行数完全由脚本定制。
 */
/*
function onQueryData(queryArgs: QueryArgs, params: JSONObject): DbDataSourceInfo | any[][] | QueryDataResultInfo {
	return null;
}
*/

/**
 * 对查询结果进行再次处理的脚本扩展点。
 * 
 * 使用场景：
 * 1. 对查询结果中的一些隐私数据作加密或者隐藏，比如数据签名，需要调用第三方系统api来进行签名验证，并且在验证成功后将签名数据隐藏。
 * 
 * 注意：
 * 1. 此脚本只适合对当前模型的单表明细查询。比如对敏感信息进行额外加密等。
 * 
 * @param resultSet 查询的结果
 * @param queryArgs 当前查询的请求参数
 * @returns 不返回结果。直接对resultSet进行处理，字段，总行数可以在脚本中进行修改，将修改后的resultSet输出给客户端。
 */
/*
function onDidQueryData(resultSet: QueryDataResultInfo, queryArgs: QueryArgs): QueryDataResultInfo {

}
*/

/**
 * 模型数据更新扩展点。
 * 
 * 程序流、表单、spg等应用修改当前模型数据前执行。
 * 
 * 常用使用场景：
 * 
 * 1. 某些情况需要个性化设置写入数据库表的字段值，可以手动修改数据包中对应字段的内容。
 * 2. 希望在写入数据前执行额外的sql，可以使用conn对象执行。
 * 3. 需要将数据写入到远程服务器，放弃执行当前数据库的更新操作，可以在执行个性化逻辑后，显式返回false。
 * 
 * @param data 写入的数据包，支持全量和增量格式。
 *   1. 全量格式：传入全部行，参考 {@link CommonTableSubmitDataPackage.allRows}
 *   2. 增量格式：传入增删改的行，参考
 *     {@link CommonTableSubmitDataPackage.deleteRows},
 *     {@link CommonTableSubmitDataPackage.addRows},
 *     {@link CommonTableSubmitDataPackage.mergeIntoRows},
 *     {@link CommonTableSubmitDataPackage.modifyRows}
 *
 * @param conn 当前数据库连接对象，程序流所有数据库执行逻辑将在同一个事务中运行。
 * 			请勿修改autoCommit设置，也不要执行提交，以免影响事务的一致性。
 * 
 * @returns 显式返回false时将不执行默认更新逻辑。
 */
function onUpdateData(data: CommonTableSubmitDataPackage, conn?: Connection): boolean {
	return true;
}

/**
 * 模型数据更新结束扩展点。
 * 
 * 程序流、表单、spg等应用修改当前模型数据后执行。
 * 
 * 常用使用场景：
 * 
 * 1. 希望在更新数据后执行额外的sql，可以使用conn对象执行。
 * 2. 数据更新后通知外部服务。
 * 
 * @param data 写入的数据包。
 * 
 * @param conn 当前数据库连接对象。
 * 			模型表的所有数据修改都会在这个连接的同一事务中执行。
 */
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 queryArgs 当前查询的请求参数
 * @return 返回null则表示无特殊处理
 */
function onCompileQuery(queryArgs: QueryRequestArgs): QueryRequestArgs {
	return null;
}

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