165 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下载及安装

• 下载地址-github：https://github.com/jiaopengzi/pbi-utils/releases

• 下载地址-gitee(国内用户)：https://gitee.com/jiaopengzi/pbi-utils/releases

• 下载地址-网盘：https://pan.baidu.com/s/1wMi0GbRA23YvRBjpZcwWFg?pwd=jiao

• pbi-utils-portable-x.x.x.x.zip 便携式，zip 文件解压后找到 pbi-utils.exe 即可使用。

• pbi-utils-setup-x.x.x.x.exe 安装文件，双击安装即可使用。

• 支持的 pbix 文件需要是 Power BI Desktop 版本： 2022年10月+ ，操作系统： win10+ 。

首页界面

三、自动生成pbit

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

1、示例文件说明

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

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

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

2、初始化

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

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

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

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

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

3、模板度量值

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

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

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

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

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

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

• 记得修改以后要保存。

4、页面编辑

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

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

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

Ⅰ、字段说明

• 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文件即可看到权限类别初始化页面。

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

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

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

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

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

• 添加 RLS 规则

  

6、权限表编辑

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

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

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

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

• 通过右键编辑

  • Power BI 帐号增加一个；

  • 页面权限 保留：1，2，3，4，5，6，7;

  • 大区ID 保留：1，2，3，4；

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

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

7、编译生成pbit

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

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

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

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

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

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

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

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

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

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

四、度量值操作

1、pbixA 2 pbixB

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

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

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

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

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

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

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

2、pbix 2 DAX

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

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

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

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

• @description：度量值描述。

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

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

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

3、DAX 2 pbix

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

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

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

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

五、关于

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

中文界面显示

英文版界面显示

六、注意事项

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