文档

配置全局参数

更新时间:

Quick BI提供全局参数来设定一些变量,在配置报表时,可以通过引用全局变量的方式支持一些需要参数变化的场景。本文为您介绍跳转、邮件订阅和报表嵌入等场景的全局参数配置方法。

背景信息

在报表的使用过程中,用户经常有这样的需求:以一个销售团队为例,如果该销售团队的业务范围是全国,那么意味着该销售团队需要随时掌握30多个省的销售情况,而且每一个省还有若干个城市,每一个城市还有若干个县;随着业务量的不断增大和扩容,该销售团队所要查阅的销售数据也会日益增加。在如此庞大且复杂的数据中,如果能够实现每一个区域的负责人只看到自己负责的那份数据,那么既可以提高相关责任人的工作效率,又可以避免泄露敏感的商业数据。

全局参数是为报表提供一个标准化的入口,允许报表使用者在预览报表时能够通过URL参数注入的方式,动态改变报表内部图表和查询控件的过滤条件,从而达到从外部控制图表内部数据展示结果的效果。全局参数的作用对象目前主要有以下两种:

  • 查询控件:查询控件接受到全局参数后,会直接以全局参数注入的条件作为默认值,绑定到某个具体的子组件上。

    说明

    实际作用的图表还需要依赖于对应子组件选择的作用范围。因为只是改变了默认值,所以其实报表使用者可以改变子组件的实际值来脱离全局参数的控制。

  • 图表:全局参数关联到的图表,本质上是在图表最后的查询SQL上拼接and片段(例如and area = '华北'),这个过程是服务器直接解析全局参数配置生成的,因此报表使用者无法更改这个结果,只能通过最终生成的sqlText来验证数据结果。

全局参数配置说明

全局参数配置的入口位于报表顶部。新建报表时,全局参数图标image.png会被隐藏起来,只有保存后才会展示。全局参数配置页面如下所示。

image.png

区域

描述

全局参数配置入口。

全局参数配置依赖于报表内部的组件数据模型,建议在每次更新完图表模型后重新配置全局参数。

设置全局参数名称。命名规则如下:

  • 长度不能超过50个字符。

  • 仅支持英文、数字和下划线。

您可以单击新建图标,新建多个全局参数。

选择参数关联控件与图表。

  • 当关联对象为查询控件时,需要选择一个查询控件内的关联条件。查询控件关联条件的展示类型,会限制后续全局参数接收值类型范围(比如无法将文本类型或者单日期格式的全局参数注入到日期区间类型的组件中),如果查询控件关联条件的展示类型有冲突,全局参数则无法正常保存。

  • 当关联对象为图表时,系统会将图表按照数据集进行分类,选择数据集中的某个字段并选中目标图表时,全局参数注入的条件会自动填充到被选中图表的SQL查询中。当选中多个数据集的字段时,选中字段的类型和粒度(年、月、日、时、分、秒)必须保持一致,否则参数配置失败。

  • 如果同时关联查询控件图表时,要求查询控件的关联条件类型必须和图表数据集的字段类型一致,并且因为查询控件的关联条件限制了输入值的模型,因此在注入全局参数时,应该尽量满足查询控件的关联条件的注入要求,才能保证查询控件和图表同时生效。

说明

为了保证参数注入的准确性和有效性,实际使用中应该尽量确保每个参数的职责是明确和单一的,谨慎将一个全局参数关联到多个查询控件,或者混合使用查询控件和数据集,如实际业务需要,建议添加多个参数分别控制不同的查询控件和图表。

字段选择:

  • 查询控件以及图表字段选择类型支持时间(暂不支持时分秒)、文本(包括地理、url)、数值类型,占位符。

    占位符配置方式请参见占位符

image

参数设置。

  • 参数名称:默认与设置的全局参数名称一致。命名规则如下:

    • 长度不能超过50个字符。

    • 仅支持英文、数字和下划线。

    说明

    参数名称未填写或参数配置出现冲突时,页面会提示报错,此时全局参数无法保存。

  • 参数别名:如果需要中文信息提示,可在此处设置。

  • 是否必须设置:选中后,查询控件和图表会去检测相应的参数是否有注入值,如果没有注入值,查询控件会优先使用编辑状态设置的默认值,图表则会取数失败(全局参数不能为空)。

  • 是否允许查询控件变更输入值:选中后,对应参数关联的子条件在预览状态下默认锁定,即无法变更查询控件子条件的操作符和值。

说明
  • 为了保证参数的有效性,全局参数的配置过程中是实时检测的,一个参数出现冲突时,所有全局参数都无法保存。

  • 全局参数配置的过程依赖当前报表的内容,报表出现变更可能会导致已经配置的全局参数注入失效,因此建议每次报表变更后复查全局参数的配置是否有效。如果全局参数的配置出现冲突时,请根据提示调整对应参数的内容。

全局参数使用场景

跳转场景

以排行榜(订单信息)跳转交叉表(商品信息)为例。

  1. 登录Quick BI控制台

  2. 进入仪表板页面。

  3. 淘宝商品订单详情仪表板中,创建商品信息交叉表,并配置交叉表全局参数。

    1. 数据页签选择销售数据为数据集,并命名为淘宝商品订单详情

      image.png

    2. 添加交叉表至仪表板中,命名为商品信息,并在仪表板顶部菜单栏,单击保存

      image

    3. 在仪表板顶部菜单栏,单击全局参数图标。

    4. 全局参数配置页面,按照下图示例,配置全局参数后,单击确定

      image

    5. 在仪表板顶部菜单栏,单击保存并发布

  4. 订单销售详情仪表板中,创建订单信息排行榜,并设置跳转至商品信息交叉表。

    1. 在仪表板编辑页面的数据页签,选择销售数据为数据集,并命名为订单销售详情

      image.png

    2. 添加如下图排行榜到仪表板,并命名为订单信息

      image.png

    3. 单击分析页签,在数据交互区域的跳转配置右侧,单击image.png图标。

      image.png

    4. 跳转页面,按照下图设置参数后,单击确定

      跳转设置更详细的操作,请参见跳转设置与展示

      image

    5. 单击排行榜订单信息中的目标订单编号,将自动跳转至仪表板淘宝商品订单详情,并显示目标订单编号的商标信息。

      跳转的页面如下图所示。

      image

邮件订阅场景

在做邮件订阅任务的时候,可以通过全局参数,给报表内的图表注入过滤条件。以下仅介绍邮件订阅中全局参数的使用,创建订阅任务的详细操作,请参见创建订阅任务

说明

邮件、钉钉工作通知、飞书通知、企业微信通知、钉钉群、飞书群和企业微信群这7种订阅方式都支持配置全局参数,本文仅介绍邮件订阅场景。

  1. 在邮件订阅的新建任务页面,设置订阅任务的内容为一个配置过全局参数的仪表板。

    设置为一个配置过全局参数的仪表板后,系统会自动带出相应的全局参数列表,且全局参数初始状态是未配置,默认不生效。订阅任务

    参数值设置为空和参数未设置是两个不同的状态。参数值设置为空,如果在关联的查询控件允许为空,会将关联条件的值重置为空值。参数值未设置,则不会对查询控件和图表造成影响。

  2. 单击操作列的图标,对全局参数进行配置。

    参数配置项的内容会随着参数关联字段的类型自动匹配。关联图表时,参数配置允许切换条件形式;关联查询控件时,只允许变更操作符和值。编辑

    完成订阅任务的参数配置后,即可保证每次在做订阅任务时,对应的参数会自动注入到报表的过滤条件中。

如您想通过配置全局参数实现不同用户订阅不同数据,请参见配置全局参数实现不同用户订阅不同数据

报表嵌入场景

报表嵌入的全局参数使用说明,请参见报表嵌入数据权限控制和传参的安全增强方案