註冊外部工具

  • 發行項

某些工具必須手動向Power BI Desktop註冊。 若要註冊外部工具，請使用下列範例程式代碼建立 JSON 檔案：

{
    "name": "<tool name>",
    "description": "<tool description>",
    "path": "<tool executable path>",
    "arguments": "<optional command line arguments>",
    "iconData": "image/png;base64,<encoded png icon data>"
}

pbitool.json 檔案包含下列元素：

  • name：提供工具的名稱，其會顯示為 Power BI Desktop 內 [外部工具] 功能區中的按鈕 標題。
  • 描述： （選擇性） 提供描述，其會顯示為 Power BI Desktop 內 [外部工具] 功能區按鈕上的工具提示。
  • path： 提供工具可執行檔的完整路徑。
  • 自變數： （選擇性） 提供應該啟動工具可執行檔的命令行自變數字串。 您可以使用下列任一佔位元：
    • %server%： 以匯入/DirectQuery 數據模型之 Analysis Services 表格式本機實例的伺服器名稱和 portnumber 取代。
    • %database%： 將 取代為匯入/DirectQuery 數據模型之 Analysis Services 表格式本機實例中裝載之模型的資料庫名稱。
  • iconData： 提供影像數據，這會在 Power BI Desktop 的 [外部工具] 功能區中轉譯為按鈕圖示。 字串應該根據沒有 “data：” 前置詞的數據 URI 語法來格式化。

將檔案 "<tool name>.pbitool.json" 命名為 ，並將它放在下列資料夾中：

  • %commonprogramfiles%\Microsoft Shared\Power BI Desktop\External Tools

針對 64 位環境，請將檔案放在下列資料夾中：

  • Program Files （x86）\Common Files\Microsoft Shared\Power BI Desktop\External Tools

啟動時，Power BI Desktop 會載入具有 .pbitool.json 擴展名之指定位置中的檔案。

範例

下列 *.pbitool.json 檔案會從External Tools 功能區啟動 powershell.exe，並執行名為 pbiToolsDemo.ps1 的腳本。 腳本會在 -Server 參數中傳遞伺服器名稱和埠號碼，以及 -Database 參數中的語意模型名稱。

{ 
    "version": "1.0.0", 
    "name": "External Tools Demo", 
    "description": "Launches PowerShell and runs a script that outputs server and database parameters. (Requires elevated PowerShell permissions.)", 
    "path": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe", 
    "arguments": "C:\\pbiToolsDemo.ps1 -Server \"%server%\" -Database \"%database%\"", 
    "iconData": "image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsEAAA7BAbiRa+0AAAANSURBVBhXY/jH9+8/AAciAwpql7QkAAAAAElFTkSuQmCC" 
}

對應的 pbiToolsDemo.ps1 腳本會將伺服器和資料庫參數輸出至主控台。

[CmdletBinding()] 
param 
( 
        [Parameter(Mandatory = $true)]         
[string] $Server, 
        [Parameter(Mandatory = $true)]         
[string] $Database  
) 
Write-Host "" 
Write-Host "Analysis Services instance: " -NoNewline 
Write-Host "$Server" -ForegroundColor Yellow 
Write-Host "Dataset name: " -NoNewline 
Write-Host "$Database" -ForegroundColor Green 
Write-Host "" 
Read-Host -Prompt 'Press [Enter] to close this window'

Screenshot of PowerShell console output created from the example external tool.

圖示數據 URI

若要在外部工具功能區中包含圖示，pbitool.json 註冊檔案必須包含iconData元素。

Screenshot of the external tools ribbon with the tool icons.

iconData 元素會採用不含 數據的數據 URI： 前置詞。 例如，一個像素洋紅色 png 影像的數據 URI 為：

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsEAAA7BAbiRa+0AAAANSURBVBhXY/jH9+8/AAciAwpql7QkAAAAAElFTkSuQmCC

請務必移除 數據： 前置詞，如 pbitool.json 先前範例所示。

若要將 .png 或其他影像檔案類型轉換成數據 URI，請使用在線工具或自定義工具，例如下列 C# 代碼段所示的工具：

string ImageDataUri; 
OpenFileDialog openFileDialog1 = new OpenFileDialog(); 
openFileDialog1.Filter = "PNG Files (.png)|*.png|All Files (*.*)|*.*"; 
openFileDialog1.FilterIndex = 1; 
openFileDialog1.Multiselect = false; 
openFileDialog1.CheckFileExists = true; 
bool? userClickedOK = openFileDialog1.ShowDialog(); 
if (userClickedOK == true) 
{ 
    var fileName = openFileDialog1.FileName; 
    var sb = new StringBuilder(); 
    sb.Append("image/") 
        .Append((System.IO.Path.GetExtension(fileName) ?? "png").Replace(".", "")) 
        .Append(";base64,") 
        .Append(Convert.ToBase64String(File.ReadAllBytes(fileName))); 
    ImageDataUri = sb.ToString(); 
}

相關內容