Mapping使用文档

1. 简介

​ mapping主要维护了mosaic数据拼接的映射关系，并提供了对象，映射表，终端，终端配置，控制码,点表等接口，用户可以通过这些接口构建object的映射关系，还具有接收fidorin原始报文数据，并转发给mosaic进行数据拼接处理的功能。

1.1 映射表脚本规则

脚本：

[FV/Code, LabelEn, LabelLocal, Category, Channel, Key, LogicExpr1, LogicExpr2，{PublicParams}]

脚本第一列：FV/Code为柔性变量， 为mosaic拼接时的变量名。如FV为”S01”，在脚本中为字符串， Code为事件的code码，当逻辑表达式2满足条件时，会根据code码来发布事件到agent，同样code码也为字符串，如”1001”为开始某事件，”1002”为结束某事件，FV命名不能以$1，$2，$3，$4，$5为后缀结尾，因为mosaic现在FV为五层缓存结构，在表达式中，如果要因为某一层的FV进行计算或比较，需要用FV名+$1的形式，如S01$1，其中$1为最地下那层，$5为最上面那层，也就是最近一次的FV数据(也就是S01==S01$5)，需要注意的是表达式中引用某一层的FV，需要加上中括号[]，如”[S01$1]+1”的形式, Code事件码一般不需要填写公共参数

脚本第二列：LabelEn为英文标签，主要对FV/Code用英文进行描述。

脚本第三列：LabelLocal为本地标签，主要对FV/Code用本地语言进行描述。

脚本第四列：Category为映射类型，主要分STA, AGT, EVNT三类映射类型。其中STA为正常处理数据，进行mosaic拼接，AGT类型为从agent订阅事件，进行mosaic数据拼接，EVNT为触发事件类，在满足逻辑表达式2的情况下，生成事件，给历程处理

脚本第五列：Channel为数据通道。当Category为STA, EVNT时，一般的格式为$AprusID-index, $CollectID-index形式字符串, 此时mapping会自动进行宏变量替换，当然AprusID或CollectID也可以写成固定形式的；当Category为AGT时， 类型为对象，格式为{}, 对象里可以填入key:value的过滤条件，mapping启动时，会根据这些条件去agent订阅事件，具体格式如{“uid”:”STATISTICS1395846800006”,”block”:”statistics”,”event”:”statistics_result”}

脚本第六列：Key为数据键名。当Category为STA, EVNT时，可以为AprusKey，离线数据的key；当Category为AGT时，为过滤订阅事件内某一value的键名，此时，键名可以写成多层key的形式，如key1.key2.key3

脚本第七列：LogicExpr1为算术表达式。主要用于值计算，使用缓存时，需要加入中括号，例如”[S01$4]+1”,也就是上一个值加上1

脚本第八列：LogicExpr2为逻辑表达式。此行映射表实际触发时，系统会首先计算此逻辑表达式2，如果此逻辑表达式的值为true则基于计算第七列的逻辑表达式1，否则直接跳过，相当于彼此触发数据直接丢弃。

脚本第九列：PublicParams为扩展参数。主要是配置FV的一些扩展参数，本列数据为json格式，如{"expire_time": "1m5s", "default_value": 1,"bypass_fv_list": ["yield_simu","yield_simu$4"], "precision": 6, "accumulate": true},详细参数说明如下：

• expire_time FV过期时间
• default_value FV默认值（当FV用于计算时，若FV不存在时使用，该值是为了保证计算能够正常进行）
• bypass_fv_list 事件携带FV列表（事件产生时，需要额外添加在事件value中的fv，可能会用于展示数据或者用于retainer中的统计）
• precision FV值为浮点数时的保留位数
• accumulate 是否开启当前fv的累加功能（注意当开启此功能时，表达式1必须为空）

1.2 算术表达式规则

1.2.1 运算符

注意：优先级值越大，表示优先级越高，如果因为运算符导致计算结果又偏差，可以使用（）来规范表达式优先级

1.2.2 函数

注意：函数内参数一般都是整数或浮点数，非特殊情况，不要填入字符串，以免造成计算错误或其他不可预知的问题

1.2.3 GFV与SFV说明

• GFV（Global Flexible Variable）即全局变量； 全局常数（可在离线数据应用中配置）会存于全局变量，数据可在映射表中引用格式格式为，引用格式格式为： ${GFV(全局变量标示)}
• SFV（Session Flexible Variable）即会话变量； 会话变量在系统运行当时可以获取值的变量。如子对象数据存于会话变量，数据可在映射表中引用。引用格式格式为： ${SFV(会话变量标示)}

1.2.4 子对象FV

允许mosaic使用 ${SFV(obj[.obj1 ...]).FV} 获取子对象FV。
如当前对象为A，子对象有B，C。如果需要获取A对象下，子对象B的S01，那么使用 ${SFV(B).S01} 来获取。
如对象B，有子对象D。如果需要获取A对象下，子对象B下的子对象D的S01，那么使用 ${SFV(B.D).S01} 来获取。

注意：获取时为该子对象FV的瞬时值。若子对象不存在，或FV不存在，则瞬时值为nil，不进行拼接及后续操作。为避免数据异常或计算异常，建议将子对象FV转为当前对象FV后，再进行使用。

1.3 映射表脚本示例

[
    ["v1", "", "STA变量-相对适配器", "STA", "$AprusID-1", "L1_3_7_2", "", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v2", "", "STA变量-相对适配器", "STA", "$AprusID-1", "L1_3_7_2", "v1+10", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v3", "", "STA变量-固定适配器", "STA", "AX20210229000249", "L1_3_7_2", "v2+10", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v4", "", "离线推送", "STA", "$CollectID-1", "Tem", "", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v5", "", "离线推送", "STA", "COL12236500002", "Tem", "", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v6", "", "统计推送", "AGT", {"uid":"STATISTICS1395846800006","block":"statistics","event":"statistics_result"}, "data", "", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v7", "", "Indass推送", "AGT", {"uid":"index1001","block":"indass","event":"indass_result"}, "index_change_accelerate", "", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v8", "", "函数计算", "STA", "$AprusID-1", "L1_3_7_2", "min(v1, v2)", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v9", "", "比较运算", "STA", "$AprusID-1", "L1_3_7_2", "v1>v2?v1:v2", "", {"expire_time": "1m5s", "default_value": 1}],
    ["v10", "", "获取子对象B的v1", "STA", "$AprusID-1", "L1_3_7_2", "${SFV(B).v1}", "", {}],
    ["v11", "", "获取子对象B的子对象D的v2", "STA", "$AprusID-1", "L1_3_7_2", "${SFV(B.D).v2}", "", {}],
    ["v12", "", "获取子对象B的S01加当前v1", "STA", "$AprusID-1", "L1_3_7_2", "${SFV(B).v1}+v1", "", {}],
    ["v13", "", "直接使用已经获取的子对象FV加当前v1", "STA", "$AprusID-1", "L1_3_7_2", "v10+v1", "", {}],
    ["v14", "", "获取不存在子对象或不存在FV(值为nil，不拼接不进行后续操作)", "STA", "$AprusID-1", "L1_3_7_2", "${SFV(noobj).nofv}", "", {}],
    ["1001", "start event", "开始事件", "EVNT", "$AprusID-1", "L1_3_7_2", "", "v1==0", {}],
    ["1002", "stop event", "停止事件", "EVNT", "$AprusID-1", "L1_3_7_2", "", "v1==1", {}],
    ["1003", "stop event", "停止事件", "EVNT", "$AprusID-1", "L1_3_7_2", "", "[v1$5]==1", {}]
]

注意：针对以上映射表脚本第一列fv命名中包含-短横线的情况，需要用[]来对命名进行转义，如[v-1]的情况