Registar uma ferramenta externa

  • Artigo

Algumas ferramentas devem ser registradas manualmente no Power BI Desktop. Para registrar uma ferramenta externa, crie um arquivo JSON com o seguinte código de exemplo:

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

O arquivo pbitool.json inclui os seguintes elementos:

  • name: forneça um nome para a ferramenta, que aparecerá como uma legenda de botão na faixa de opções Ferramentas Externas no Power BI Desktop.
  • descrição: (opcional) Forneça uma descrição, que aparecerá como uma dica de ferramenta no botão da faixa de opções Ferramentas Externas no Power BI Desktop.
  • path: Forneça o caminho totalmente qualificado para o executável da ferramenta.
  • argumentos: (opcional) Forneça uma cadeia de argumentos de linha de comando com os quais o executável da ferramenta deve ser iniciado. Você pode usar qualquer um dos seguintes espaços reservados:
    • %server%: substituído pelo nome do servidor e número da porta da instância local do Analysis Services Tabular para modelos de dados importados/DirectQuery.
    • %database%: substituído pelo nome do banco de dados do modelo hospedado na instância local do Analysis Services Tabular para modelos de dados importados/DirectQuery.
  • iconData: forneça dados de imagem, que serão renderizados como um ícone de botão na faixa de opções Ferramentas Externas no Power BI Desktop. A cadeia de caracteres deve ser formatada de acordo com a sintaxe para URIs de dados sem o prefixo "data:".

Nomeie o arquivo "<tool name>.pbitool.json" e coloque-o na seguinte pasta:

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

Para ambientes de 64 bits, coloque os arquivos na seguinte pasta:

  • Arquivos de Programas (x86)\Common Files\Microsoft Shared\Power BI Desktop\External Tools

Os arquivos nesse local especificado com a extensão .pbitool.json são carregados pelo Power BI Desktop na inicialização.

Exemplo

O seguinte arquivo *.pbitool.json inicia o powershell.exe da faixa de opções Ferramentas Externas e executa um script chamado pbiToolsDemo.ps1. O script passa o nome do servidor e o número da porta no parâmetro -Server e o nome do modelo semântico no parâmetro -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" 
}

O script pbiToolsDemo.ps1 correspondente produz os parâmetros Server e Database para o console.

[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.

URIs de dados de ícone

Para incluir um ícone na faixa de opções Ferramentas Externas, o arquivo de registro pbitool.json deve incluir um elemento iconData.

Screenshot of the external tools ribbon with the tool icons.

O elemento iconData usa um URI de dados sem o prefixo data: . Por exemplo, o URI de dados de uma imagem png magenta de um pixel é:

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

Certifique-se de remover o prefixo data: , conforme mostrado no exemplo anterior pbitool.json.

Para converter um .png ou outro tipo de arquivo de imagem em um URI de dados, use uma ferramenta online ou uma ferramenta personalizada, como a mostrada no seguinte trecho de código 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(); 
}

Conteúdos relacionados