附录A：自动报表脚本规范

Mixiot 报表的机制很简单，将需要的报表设计一个 Excel 模板，然后填充数据生成实际报表。其中，如何填充数据是脚本配置的。

报表脚本示例

{
    "工作簿1名称":[
        {
            "field":"data",
            "block_id":"apim",
            "position":{
                "to":"",
                "from":"A_1"
            },
            "sequence":"cellData",
            "condition":{
                "action":"get_last_statistics",
                "script_uid":"STATISTICS1410094400003"
            },
            "format_function":""
        },
        {
            "field":"data",
            "block_id":"apim",
            "position":{
                "to":"B_10",
                "from":"B_1"
            },
            "sequence":"columnData",
            "condition":{
                "items":10000,
                "action":"get_statistics_list",
                "end_time":"2021-06-30 00:00:00",
                "object_id":"OBJ1343477200007",
                "mapping_id":"",
                "script_uid":"",
                "start_time":"2021-03-29 00:00:00"
            },
            "format_function":""
        },
        {
            "field":"data",
            "block_id":"apim",
            "position":{
                "to":"H_1",
                "from":"C_1"
            },
            "sequence":"rowData",
            "condition":{
                "items":10000,
                "action":"get_statistics_list",
                "end_time":"2021-06-30 00:00:00",
                "object_id":"OBJ1343477200007",
                "mapping_id":"",
                "script_uid":"",
                "start_time":"2021-03-29 00:00:00"
            },
            "format_function":""
        },
        {
            "field":"id,data,created",
            "block_id":"apim",
            "position":{
                "to":"H_3,H_4,H_5",
                "from":"B_3,B_4,B_5"
            },
            "sequence":"columnTableData",
            "condition":{
                "items":10000,
                "action":"get_statistics_list",
                "end_time":"2021-06-30 00:00:00",
                "object_id":"OBJ1343477200007",
                "mapping_id":"",
                "script_uid":"",
                "start_time":"2021-03-29 00:00:00"
            },
            "format_function":""
        },
        {
            "field":"id,data,created",
            "block_id":"apim",
            "position":{
                "to":"A_18,B_18,C_18",
                "from":"A_8,B_8,C_8"
            },
            "sequence":"rowTableData",
            "condition":{
                "items":10000,
                "action":"get_statistics_list",
                "end_time":"2021-06-30 00:00:00",
                "object_id":"OBJ1343477200007",
                "mapping_id":"",
                "script_uid":"",
                "start_time":"2021-03-29 00:00:00"
            },
            "format_function":""
        }
    ]
}

报表脚本说明

由上述脚本示例可知，JSON 中的第一层主体格式为 Key-Value 格式；其中，Key 为每一个 Excel 的工作簿（Sheet）的名称，Value 则为需要在此工作簿中渲染的数据对象。

注：value 是很多 object 类型数据的列表，其中，每一个 object 都填充自己内部声明指定的单元格，具体规则在 字段解释 章节进行说明

综上，如果一个模板包含多个工作簿（sheet），则数据源脚本格式应如下设置：

{
    "工作簿1名称":[
       {
            "field":"data",
            "remark":"上月数据",
            "block_id":"apim",
            "position":{
                "from":"A_1",
                "to":""
            },
            "sequence":"rowTableData",
            "condition":{
                "start":"date('Y-m-01 00:00:01',strtotime('-1 months'))",
                "end":  "date('Y-m-01 00:00:00', time())",
                "action":"get_statistics_list",
                "order_by":"[\"created\", \"asc\"]",
                "object_id":"A161205_20",
                "script_uid":"ST_ProduceSteam_Day"
            },
            "format_function":""
        }
    ],
    "工作簿2名称":[
         {
            "field":"data",
            "block_id":"apim",
            "position":{
                "from":"A_1",
                "to":""
            },
            "sequence":"rowTableData",
            "condition":{
                "action":"get_last_statistics",
                "script_uid":"STATISTICS1410094400003"
            },
            "format_function":""
        }
    ]
}

报表脚本字段解释

我们只拿一个工作簿的字段进行具体讲解（多工作簿的脚本同理）。

字段概要

每个工作簿中，每个对象的主要属性如下：

sequence

position

position是一个对象，只有from和to属性

• from：从哪个单元格开始，列_行,如A_2
• to: 到哪个单元格结束，列_行,如A_2

"position":{"from":"A_2","to":"A_11"}

注：这个参数是配合sequence属性选择数据范围的

1.3.4. format_function

如果需要对请求block的返回结果进行二次处理，则需要在此填写函数名，模板如下：

"format_function":"[{\"from\":\"start_time\",\"function\":\"format_date\",\"to\":\"start_time\"}]"

说明：

• format_functoin参数值为json字符串（字符串解析后为数组，需要用方括号括起来）
  • from 来源字段
  • function 执行的函数名
  • to 输出字段

function 当前实现的有：

format_month 输出 2022-06
format_date  输出 2022-06-23
format_hour  输出 12:00
format_week  输出 26    //第几周

condition

condition是一个key-value的一维对象，里边的key是根据接口要求设置的，具体详见block接口文档。

时间类型的参数

目前，统计计算接口中已经支持时间属性有4个，分别是 *”start”、”end”、”id”、”created”*;他们均支持写php的date函数来定义接口传参所需的时间，比如：

start:"date('Y-m-d 07:00:00',time())", // start为每天 07:00:00
end:"date('Y-m-d 08:00:00',time())", // end为每天 08:00:00
where_and:"[[\"created\",\"=\",\"date('Y-m-d H:i:s', strtotime(date('Y-m', time()) . '-01 00:00:00'))\"]]", // created为每个月1号

具体写法可参考 php 取时间

常用php时间段

start ≤ end_time ≤ end ; end_time为 apim get_statistics_list接口返回值

field

field参数是需要解析的api接口返回的字段，如果是一个字段，则直接输入对应字段名称即可，比如：

field:"data"

如果多列|行单元格的时候，可以以英文逗号分隔字段设置，比如：

field:"id,created,data"

但有时统计计算返回的data属性（或者任意一个名字都可以）并不是一个字符串，而是一个数组，而我们想取数组下某一个元素时，此时可如下设置：

// data的值 ["360.00","198.99"]
// data|0 则取data的第一个元素=》"360.00" ，data|1 则取data的第二个元素=》"198.99"，以此类推
field:"id,created,data|0

block

block参数代表需要被访问的数据源的block标识，具体参考mixiot的block_id的枚举。

tableman报表脚本示例

对于插入tableman的数据，需要首先在tableman系统中创建表格，然后脚本才能正常执行。

tableman的脚本跟excel脚本有部分差异：

{
    "report_table1":[
        {
            "block_id":"apim",
            "condition":{
                "items":5,
                "action":"get_statistics_list",
                "object_id":"OBJ1684490200006"
            },
            "field":"data,start_time,end_time",
            "table_field":"data1,data2,data3",
            "format_function":""
        }
    ],
    "report_table2":[
        {
            "block_id":"apim",
            "condition":{
                "items":5,
                "action":"get_statistics_list",
                "object_id":"OBJ1684490200006"
            },
            "field":"data,start_time,end_time",
            "table_field":"value1,value2,value3",
            "format_function":""
        }
    ]
}

tableman每个工作簿中，每个对象的主要属性如下：

对于 field 和 table_field 的对应关系，这里详细说明一下：

上面的脚本表示：

接口获取的数据包含 data, start_time, end_time 字段，

希望将 data 放到 report_table1表的 data1，

start_time 放到 report_table1 表的 data2，

end_time 放到 report_table1 表的 data3。

report_table2 的情况相同。