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 处变化：
- 页面编辑里面的显示名称及页数和层级结构。
- 模板度量值中的度量值
- pbi-utils 工具后台自动写入的导航度量值，文件夹 test02 是我们自己在编译时候写的。
- rls 文件夹下的度量值，即我们在权限类别初始化的 rls 名称。
- 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 中的表。
五、关于
在关于页面主要是我们的联系方式、使用文档以及我们的视频课推介，我们做了中文和英文两种语言的显示。可以通过下方语言选择切换。
中文界面显示
英文版界面显示
六、注意事项
- 我们在操作 pbix 的时候，并没有在原本的 pbix 文件上操作，对于我们原本文件的安全性有了保证，不会破坏原来的文件。
- 我们所有生成的 pbit 文件是 Power BI 模板文件，里面不会包含数据，只有对应的元数据，当我们确认好使用后，请及时另存为 pbix 。
- 在生成多页导航的 pbit 中，还可以根据自己的需求重新修改来实现个性化的 Home、Navigation 和 NoPermission 等页面。
- 已知一部分老版本 Power BI Desktop 生成的 pbix 文件会出现不可知的一些问题，请升级到最新版本的 Power BI Desktop 后另存一份即可。
自由转载-非商用-非衍生-保持署名（创意共享3.0许可证）
