Compartilhar via

Registrar uma ferramenta externa

  • Artigo

Algumas ferramentas precisam ser registradas manualmente com o 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: fornece um nome para a ferramenta, que aparece como uma legenda de botão na faixa de opções de Ferramentas Externas no Power BI Desktop.
  • description: (opcional) fornece uma descrição, que será exibida como uma dica de ferramenta na faixa de opções de Ferramentas Externas do Power BI Desktop.
  • path: fornece o caminho totalmente qualificado para o executável da ferramenta.
  • arguments: (opcional) fornece uma cadeia de caracteres de argumentos da linha de comando com a qual 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 de porta da instância local do Tabular dos Analysis Services para modelos de dados importados/DirectQuery.
    • %database%: substituído pelo nome do banco de dados do modelo hospedado na instância local do Tabular dos Analysis Services para modelos de dados importados/DirectQuery.
  • iconData: fornece dados da 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 arquivo *.pbitool.json a seguir inicia powershell.exe na 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 gera os parâmetros de Servidor e de Banco de Dados 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 bipbitool.json precisa 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

Remova o prefixo data:, conforme mostrado no exemplo pbitool.json anterior.

Para converter um .png ou outro tipo de arquivo de imagem em um URI de dados, use uma ferramenta online ou personalizada, como a mostrada no seguinte snippet 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údo relacionado