pbi-utils 使用文档

165 pbi-utils 使用文档

一、背景

先来说一下为什么会有 pbi-utils 这个小工具吧。在我日常做演示的示例文件的时候,每次都要重新搞一次 Power BI Desktop,就想能不能像 PPT 模板那样,搞一个模板,然后更专心的去专注内容本身呢?一段时间来,我其实也是用的这种方式,自己存有一份示例模板,这样每次另存一份就 ok 了。

直到有一天我要做关于 Power BI 行级别安全性 (Row-level security,简称 RLS) 的示例的时候,发现用这样模板另存就没办法去适配不同的业务模型了。

于是开始思考,是否能把这种 RLS 抽象出来,同时能把兼具模板,最好还能兼具到页面权限,还能一键生成那该多好。这就是 pbi-utils 最初设想,但面对 Power BI 要去操控数据模型目前可以是用 Tabular Editor(https://tabulareditor.github.io/),但是没法操控新建页面等。这个是事情也就搁置了

直到有一天在 sqlbi(https://www.sqlbi.com/) 上看到了一个名叫 pbi-tools(https://pbi.tools/) 的工具,pbi-tools 可以完全把 pbix 文件完成拆解成模型(model)和报告(report),这就可以二次开发了。于是便有了 pbi-utils 这个小工具。

在此特别感谢 @mthierba(pbi-tools作者)。

在 pbi-utils 中使用了 pbi-tools 一部分功能,更多功能大家有兴趣去 pbi-tools 主页看看,这是一个非常棒的工具。

pbi-utils 整体框架如下:

框架

二、pbi-utils下载及安装

首页界面

首页

三、自动生成pbit

在做使用文档前,我们先说一下我的基本思路。说来也比较简单,就是通过单独的 json 配置文件,把我们需要的一些配置单独解耦出来。我通过操作配置文件即可完成 Power BI 调整需求。

1、示例文件说明

先来交代一下,我们一般拿到的都是业务数据,创建基础的报告模型壳子就可以加个 pbi-utils。

依然使用之前分享给大家的 demo 数据(https://jiaopengzi.com/1435.html)

我们拿到的是一个只导入了业务数据,没有报告页面的 pbix 文件。

165-1

2、初始化

首先我们需要对我们 pbix 文件进行 json 配置文件初始化。

内容页数规则:只能是 1-99 的整数,如果需要多个二级分类,则使用英文半角逗号分开;其它内容无法输入。

165-2

下图所示,我们以为 C:/desktop/demo/demo.pbix 为业务模板,内容页数:3,4 表示我们需要两个二级分类的页面导航,同时第一个分类内容页数为3页,第二个分类的内容页数为4页。

当然还有一个页面 URL 名称是否使用随机值,这目的其实是为了伪页面权限准备的,在视频中我们再介绍。

点击初始化后即可得到我们 json 配置文件C:/desktop/demo/demo.json

165-3

3、模板度量值

在 模板度量值 下选择前面初始化的C:/desktop/demo/demo.json文件即可看到模板度量值。

165-4

  • 我把我常用的一些模板度量值做成了模板给到大家。当然这些都可以自定义,当你每一次保存的时候,下次初始化的时候就将使用你保存过的模板度量值作为模板。所以大家可以根据自己需要增减。

  • 如果我们前面的 pbix 模板中有度量值了的话,请不要和这里的度量值重名。

  • 度量值类别中我们增加了一个 报表刷新时间,如果启用勾选去掉,则是按照自动刷新时间来显示,打上勾则是按照赋值的内容显示。

  • 图片 URL 兼容 图片的 URL 链接和 SVG 格式。

  • 可以通过右键进行 删除、编辑和多行输入;多行输入字段间使用 | 分割,多行用换行。

  • 记得修改以后要保存。

165-5

4、页面编辑

在 页面编辑 下选择前面初始化的C:/desktop/demo/demo.json文件即可看到页面配置文件。

这里的页面的属性,是使用我的给大家的模板,在使用的时候,只要保存后,以后初始化的时候则会使用自己的模板,非常的人性。

页面编辑是没有新增和删除的,所以是在我们前面做报告规划的时候就需要考虑清楚的,只能通过初始化来确认页面的数量和分级。

165-6

Ⅰ、字段说明

  • ID: 页面的索引从 0 开始,不能编辑。

  • url名称: 页面名称,在 Power BI 服务中 url 中的使用;名称不能重复。

  • 显示名称: Power BI 页面的显示名称。

  • 页面视图: 页面视图 1 调整到页面大小 , 2 适应宽度 , 3 实际大小。

  • 页面高度: 正整数。

  • 页面宽度: 正整数。

  • 页面垂直对齐: 分选项为:'Top', 'Middle' ;注意单引号的保留。

  • 页面隐藏属性: 0 为不隐藏, 1 隐藏。

  • 页面标题文字: 页面标题文字。

  • 页面标题文字颜色: 使用16进制颜色,加上透明度,末尾两位00表示完全透明,FF完全不透明。

  • 页面标题背景颜色: 使用16进制颜色,加上透明度,末尾两位00表示完全透明,FF完全不透明。

  • 导航按钮名称: 导航按钮名称(选择窗格中查看)。

  • 导航按钮页面中显示名称: 导航按钮页面中显示内容。

  • 导航按钮文字颜色-有权限: 使用16进制颜色,加上透明度,末尾两位00表示完全透明,FF完全不透明。

  • 导航按钮文字颜色-无权限: 使用16进制颜色,加上透明度,末尾两位00表示完全透明,FF完全不透明。

  • 导航按钮背景颜色-有权限: 使用16进制颜色,加上透明度,末尾两位00表示完全透明,FF完全不透明。

  • 导航按钮背景颜色-无权限: 使用16进制颜色,加上透明度,末尾两位00表示完全透明,FF完全不透明。

  • 导航按钮鼠标放上去的工具提示-有权限: 导航按钮鼠标放上去的工具提示文字-有权限。

  • 导航按钮鼠标放上去的工具提示-有权限: 导航按钮鼠标放上去的工具提示文字-有权限。

  • 备注: 备注说明,可以留空。

Ⅱ、页面层级导航示意图

Home
└─Navigation
    ├─NoPermission
    ├─A00
    │  ├─A01
    │  ├─A02
    │  ├─...
    │  └─A99
    ├─B00
    │  ├─B01
    │  ├─B02
    │  ├─...
    │  └─B99
    ├─...
    └─Z00
        ├─Z01
        ├─Z02
        ├─...
        └─Z99
  • Home:首页,建议名称保留不变

  • Navigation:总导航页,导航至第二层导航页,即:A00-Z00,A至Z表示分类,理论上有26个分类,数字使用两个零表示,如果内容页只有一个分类的话则默认只有 Navigation 一个导航页。

  • 内容页:A01...A99, B01...B99 ... Z01...Z99;分类用字母表示,内容页从 01 至 99,理论上每个分类可以有 99 个页面,加上分类可以得到 26 * 100= 2600内容页面,基本能满足 Power BI 各种层级导航需求了。当然初始化后,这些名称都是可以根据业务需求自定义的。

  • NoPermission:无权限提示页,用户无权限的时候跳转的页面。

5、权限类别初始化

权限类别初始化主要是针对 RLS 。如果没有 RLS 需求的则可以跳过当前设置。

在 权限类别初始化 页面选择前面初始化的C:/desktop/demo/demo.json文件即可看到权限类别初始化页面。

165-7

当前是没有任何的 RLS 配置,如果需要则按照下列配置填写保存即可。

  • rls名称:即你需要添加的 rls 规则的度量值名称,字母下划线和数字的组合输入其它无效,不能与 pbix 中原有度量值重名。

  • 表格:表格会通过前面我们的初始化获得对应表格的名称。

  • 字段:当表格更新后,即可获得表格对应的字段。

  • 字段值:字段值是当前字段所有的取值,目的是类别初始化后备用。

  • 添加 RLS 规则

    165-8

6、权限表编辑

在 权限表编辑 页面选择前面初始化的C:/desktop/demo/demo.json文件即可看到权限表编辑页面。

165-9

  • 默认情况下,会根据用户所在电脑的账户生成一条对应本机用户权限。

  • 权限包括 页面序号 和 RLS 权限,RLS 权限则是我们前面使用权限类别初始化的数据。

  • 一个用户名称会有正常的 Power BI 帐号,同时在本机上也需要对应的账户名称来支持本地用户的权限。

  • 通过右键编辑

    • Power BI 帐号增加一个;

    • 页面权限 保留:1,2,3,4,5,6,7;

    • 大区ID 保留:1,2,3,4;

    • 产品分类 保留:A类,B类,C类。

165-10

当然也可以通过新增按钮增加更多的帐号配置,记得保存。

7、编译生成pbit

在 编译生成pbit 页面,到了这里,基本上我们的配置就做好了,可以生成我们需要的页面了。

  • 选择我们的 pbix 模板。
  • 选择我们已经配置好的配置文件C:/desktop/demo/demo.json
  • 选择需要存放度量值的表格。
  • 度量值文件夹自定义,建议使用字母下划线数字来组合,用来存放我们的导航和必要元素的度量值。

点击 生成pbit 按钮,片刻后就能看到 pbit 创建成功的提示。

165-11

在我们 pbix 文件的同目录下会创建一个 pbix 名称关键字文件夹。

165-12

打开文件夹下的 pbit 文件,确认加载,可以看到我们的页面已经从最开始的只有一个空白页,到现在符合我们配置的页面创建成功了。

165-13

注意其中标注数字的 5 处变化:

  1. 页面编辑里面的显示名称及页数和层级结构。
  2. 模板度量值中的度量值
  3. pbi-utils 工具后台自动写入的导航度量值,文件夹 test02 是我们自己在编译时候写的。
  4. rls 文件夹下的度量值,即我们在权限类别初始化的 rls 名称。
  5. pbi-utils 工具后台自动写入的辅助表格。

同时关注 RLS, 在建模->通过以下身份查看->可以看到我们多了一个 rls 角色。我们拉一个和我们配置文件中 RLS 权限相关的维度矩阵。

165-14

当我们点击确认后,可以发现和我们配置的 RLS 是一致的。

165-15

还有包括页面权限等,请观看我们的演示视频。

四、度量值操作

1、pbixA 2 pbixB

在 pbixA 2 pbixB 页面,这里的 2 表示 to 的意思。

我们把前面的 pbit 文件保存为 A.pbix,新建了一个 B.pbix 文件,没有任何度量值。

165-16

选择对应的 A.pbix 和 B.pbix,点击加载数据

165-17

稍等片刻后,可以看到一个多行编辑的弹窗,在这里我们选择需要导入到 B.pbix 度量值,并选择好度量值表,点击提交。

165-18

可以看到提示,在 B.pbix 的同目录下,生成了一个 B.pbit 的文件。

165-19

打开 B.pbit,可以开电脑我们前面导入的度量值都进来了。这样我们从 pbixA 到 pbixB 的度量值就导入好了。

我们看到有黄色叹号,这是因为我们的 B.pbix 中并没有我们 A.pbix 中的表,所以在使用导入功能前,一定要搞清楚这些度量值导入后是否有意义。

165-20

2、pbix 2 DAX

在 pbix 2 DAX 页面中,我们选择对应的 pbix 文件和对应的文件夹;点击按钮 导出DAX。

165-21

我们打开提示的路径,就可以看到导出的度量值了。

165-22

165-23

导出的度量值中,名称中有一个分隔符 ][ 分隔符前是存放度量值的表,分隔符之后是度量值名称。

在导出的度量值中,最前面的注释是后续导入需要的,请不要随意删除。

  • @description:度量值描述。

  • @displayFolder:度量值所在文件夹。

  • @formatString:度量值的格式化字符串。

  • @dataCategory:度量值的数据类别。

3、DAX 2 pbix

DAX 2 pbix 和 pbix 2 DAX 就是一个逆向的过程。

首先需要读取到导入的 pbix 文件,目的是拿到对应的度量值表,读取完成后,可以选择对应的度量值表。

选择上述导出的度量值文件夹,点击 导入DAX。

165-24

可以看到提示消息,在我们需要导入的 C.pbix 文件的同目录下,创建了一个 C.pbit 文件。打开查看,可以看到文件夹里面的度量值都导入进来了,和前面 pbixA 2 pbixB一样,我们看到有黄色叹号,这是因为我们的 C.pbix 中并没有我们 A.pbix 中的表。

165-25

五、关于

在关于页面主要是我们的联系方式、使用文档以及我们的视频课推介,我们做了中文和英文两种语言的显示。可以通过下方语言选择切换。

中文界面显示

165-26

英文版界面显示

165-27

六、注意事项

  1. 我们在操作 pbix 的时候,并没有在原本的 pbix 文件上操作,对于我们原本文件的安全性有了保证,不会破坏原来的文件。
  2. 我们所有生成的 pbit 文件是 Power BI 模板文件,里面不会包含数据,只有对应的元数据,当我们确认好使用后,请及时另存为 pbix 。
  3. 在生成多页导航的 pbit 中,还可以根据自己的需求重新修改来实现个性化的 Home、Navigation 和 NoPermission 等页面。
  4. 已知一部分老版本 Power BI Desktop 生成的 pbix 文件会出现不可知的一些问题,请升级到最新版本的 Power BI Desktop 后另存一份即可。