Partilhar via

API de download de arquivos

  • Artigo

A API de download de arquivos permite que os usuários baixem dados de um visual personalizado para um arquivo em seu dispositivo de armazenamento. O download de um visual requer o consentimento do usuário e a permissão de administrador fornecida na opção global de administrador. 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 sua organização.

Captura de ecrã da definição de administrador que permite transferências visuais personalizadas.

Nota

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

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

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

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

Antes do download começar, uma janela aparece pedindo para confirmar se o visual é de uma fonte confiável.

Captura de ecrã a pedir para confirmar a transferência apenas se for de uma fonte fidedigna.

Como usar a API de download de arquivos

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

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

A diferença entre os dois métodos é o valor de retorno.

O status método

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

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

O exportVisualsContent método

O exportVisualsContent método tem quatro parâmetros:

  • conteúdo: string
  • nome do arquivo: string
  • fileType: string - Ao exportar para um arquivo .pdf ou .xlsx , o fileType parâmetro deve ser base64
  • fileDescrição: string

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

O exportVisualsContentExtended método

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

  • conteúdo: string
  • nome do arquivo: string
  • fileType: string - Ao exportar para um arquivo .pdf ou .xlsx , o fileType parâmetro deve ser base64
  • fileDescrição: 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 foi concluído com sucesso.
  • Nome do arquivo – O nome do arquivo exportado.

Exemplo: API de download de arquivos

Aqui está 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 é suportada apenas no serviço do Power BI e no Power BI Desktop
  • O limite de tamanho para um ficheiro transferido é de 30 MB.
  • Esta API é uma API privilegiada.

Conteúdos relacionados