File download API

  • Articolo

L'API di download dei file consente agli utenti di scaricare i dati da un oggetto visivo personalizzato in un file nel dispositivo di archiviazione. Il download di un oggetto visivo richiede il consenso dell'utente e l'autorizzazione di amministratore fornita nel commutatore globale amministratore. Questa impostazione è separata da e non è interessata dalle restrizioni di download applicate nelle impostazioni del tenant di esportazione e condivisione dell'organizzazione.

Screenshot dell'impostazione dell'amministratore che abilita i download di oggetti visivi personalizzati.

Nota

L'API di download dei file include tre metodi:

Usare l'API di download dei file per esportare nei file dei tipi seguenti:

  • .txt
  • .csv
  • .json
  • .tmplt
  • .xml
  • PDF
  • XLSX

Prima dell'inizio del download, viene visualizzata una finestra in cui viene chiesto di confermare che l'oggetto visivo proviene da un'origine attendibile.

Screenshot che chiede di confermare il download solo se proviene da un'origine attendibile.

Come usare l'API di download dei file

Per usare l'API di download dei file, aggiungere una dichiarazione alla matrice di privilegi nelle funzionalità visive.

L'API di download dei file include tre metodi:

La differenza tra i due metodi è il valore restituito.

Metodo status

Il metodo status restituisce lo stato dell'API di download del file:

  • PrivilegeStatus.DisabledBy Amministrazione: l'opzione dell'amministratore tenant è disattivata
  • PrivilegeStatus.NotDeclared: l'oggetto visivo non ha alcuna dichiarazione per l'archiviazione locale nella matrice dei privilegi
  • PrivilegeStatus.NotSupported: l'API non è supportata. Per altre informazioni, vedere Limitazioni .
  • PrivilegeStatus.Allowed: l'API è supportata e consentita.

Metodo exportVisualsContent

Il exportVisualsContent metodo ha quattro parametri:

  • content: string
  • filename: string
  • fileType: string - Quando si esegue l'esportazione in un file .pdf o .xlsx , il fileType parametro deve essere base64
  • fileDescription: stringa

Questo metodo restituisce una promessa che verrà risolta per un valore booleano.

Metodo exportVisualsContentExtended

Il exportVisualsContentExtended metodo ha anche quattro parametri:

  • content: string
  • filename: string
  • fileType: string - Quando si esegue l'esportazione in un file .pdf o .xlsx , il fileType parametro deve essere base64
  • fileDescription: stringa

Questo metodo restituisce una promessa, che verrà risolta con un risultato di tipo ExportContentResultInfo che contiene i parametri seguenti:

  • downloadCompleted: se il download è stato completato correttamente.
  • filename: il nome del file esportato.

Esempio: API di download di file

Ecco un esempio di come scaricare il contenuto di un oggetto visivo personalizzato in un file di Excel e in un file di testo.

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
            }
        }
    }
}

Considerazioni e limitazioni

  • L'API è supportata solo nei servizio Power BI e in Power BI Desktop
  • Il limite di dimensioni per un file scaricato è 30 MB.
  • Questa API è un'API con privilegi.

Contenuto correlato