共用方式為

註冊外部工具

  • 發行項

某些工具必須以手動方式向 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 檔案包含下列元素：

  • 名稱：提供工具的名稱，這會在 Power BI Desktop 內的 [外部工具] 功能區中顯示為按鈕標題。
  • description：(選擇性) 提供描述，這會在 Power BI Desktop 內的 [外部工具] 功能區按鈕上顯示為工具提示。
  • 路徑：提供工具可執行檔的完整路徑。
  • arguments：(選擇性) 提供應和工具可執行檔一起啟動的命令列引數字串。 您可以使用下列任何預留位置：
    • %server%：針對匯入/DirectQuery 資料模型，以 Analysis Services 表格式本機執行個體的伺服器名稱與連接埠號碼取代。
    • %database%：針對匯入/DirectQuery 資料模型，以 Analysis Services 表格式本機執行個體中裝載之模型的資料庫名稱取代。
  • iconData：提供影像資料，這會在 Power BI Desktop 內的 [外部工具] 功能區中呈現為按鈕圖示。 字串應該根據資料 URI 的語法來格式化，且不含 "data:" 前置詞。

將檔案命名為 "<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'

從範例外部工具建立的 PowerShell 主控台輸出螢幕擷取畫面。

圖示資料 URI

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

外部工具功能區的螢幕擷取畫面，其中具有工具圖示。

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

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

請務必移除 data: 前置詞，如上述範例 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(); 
}

相關內容