Compartilhar via

API de download de arquivo

  • Artigo

A API de download de arquivo permite que os usuários baixem dados de um visual personalizado em um arquivo em seu dispositivo de armazenamento. Baixar um visual requer o consentimento do usuário e a permissão do administrador, fornecida na opção de administrador global. Essa configuração é separada e não é afetada pelas restrições de download aplicadas nas configurações de locatário de exportação e compartilhamento da organização.

Captura de tela da configuração de administrador habilitando downloads de visuais personalizados.

Observação

A API de download de arquivos possui três métodos:

  • exportVisualsContent: disponível a partir da versão 4.5 da API
  • status está disponível na API versão 4.6.
  • exportVisualsContentExtended está disponível a partir da versão 5.3 da API.
  • Para descobrir qual versão você está usando, verifique apiVersion no arquivo pbiviz.json.

Use a API de download de arquivo para exportar para arquivos dos seguintes tipos:

  • .txt
  • .csv
  • .json
  • .tmplt
  • .xml
  • .pdf
  • .xlsx

Antes de o download começar, aparecerá uma janela solicitando que você confirme que o elemento visual vem de uma fonte confiável.

Captura de tela solicitando que o download seja confirmado apenas se for de uma fonte confiável.

Como usar a API de download de arquivo

Para usar a API de download de arquivo, adicione uma declaração à matriz privilégios em recursos visuais.

A API de download de arquivos possui três métodos:

O valor retornado será a diferença entre os dois métodos.

O método status

O método status retorna o status da API de download de arquivo:

  • PrivilegeStatus.DisabledByAdmin: a opção de administração do locatário está desativada
  • PrivilegeStatus.NotDeclared: o visual não possui declaração para o armazenamento local na matriz de privilégios
  • PrivilegeStatus.NotSupported: a API não é suportada. Veja limitações para mais informações.
  • PrivilegeStatus.Allowed: a API é suportada e permitida.

O método exportVisualsContent

O método exportVisualsContent tem quatro parâmetros:

  • content: string
  • filename: string
  • fileType: string: ao exportar para um arquivo .pdf ou .xlsx o parâmetro fileType deve ser base64
  • fileDescription: string

Esse método retorna uma promessa que será resolvida para um valor booliano.

O método exportVisualsContentExtended

O método exportVisualsContentExtended também tem quatro parâmetros:

  • content: string
  • filename: string
  • fileType: string: ao exportar para um arquivo .pdf ou .xlsx o parâmetro fileType deve ser base64
  • fileDescription: string

Esse método retorna uma promessa que será resolvida com um resultado do tipo ExportContentResultInfo que contém os seguintes parâmetros:

  • downloadCompleted – se o download for concluído com êxito.
  • filename – o nome do arquivo exportado.

Exemplo: API de download de arquivo

Veja um exemplo de como baixar o conteúdo de um visual personalizado em um arquivo do Excel e um arquivo de texto.

import IDownloadService = powerbi.extensibility.IDownloadService;
...

export class Visual implements IVisual {
    ...
    private downloadService: IDownloadService;
    ...

    constructor(options: VisualConstructorOptions) {
        this.downloadService = options.host.downloadService;
         ...

        const downloadBtn: HTMLElement = document.createElement("button");
        downloadBtn.onclick = () => {
            let contentXlsx: string = ...;//content in base64
            let contentTxt: string = ...;
            this.downloadService.exportVisualsContent(contentTxt, "mytxt.txt", "txt", "txt file").then((result) => {
                if (result) {
                    //do something
                }
            }).catch(() => {
                //handle error
            });

            this.downloadService.exportVisualsContent(contentXlsx, "myfile.xlsx", "base64", "xlsx file").then((result) => {
                if (result) {
                    //do something
                }
            }).catch(() => {
                //handle error
            });

            this.downloadService.exportVisualsContentExtended(contentXlsx, "myfile.xlsx", "base64", "xlsx file").then((result) => {
                if (result.downloadCompleted) {
                    //do something
                    console.log(result.fileName);
                }
            }).catch(() => {
                //handle error
            });
        };

        // if you are using API version > 4.6.0
        downloadBtn.onclick = async () => {
            try {
                const status: powerbi.PrivilegeStatus = await this.downloadService.exportStatus();
                if (status === powerbi.PrivilegeStatus.Allowed) {
                    const result = await this.downloadService.exportVisualsContent('aaaaa','a.txt', 'text/plain', 'aa');
                    // handle result
                } else {
                    // handle if the API is not allowed
                }

            } catch (err) {
                //handle error
            }
        }
    }
}

Considerações e limitações

  • A API tem suporte apenas no serviço do Power BI e no Power BI Desktop
  • O limite de tamanho para um arquivo baixado é de 30 MB.
  • Essa API é uma API privilegiada.

Conteúdo relacionado