API di download dei file

  • Articolo

L'API di download di 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 dell'amministratore fornita nelle opzioni globali dell'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 degli 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, compare una finestra in cui viene chiesto di confermare che l'oggetto visivo proviene da una fonte attendibile.

Screenshot che chiede di confermare il download solo se proviene da una fonte 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 stato restituisce lo stato dell'API di download dei file:

  • PrivilegeStatus.DisabledByAdmin: 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 ulteriori informazioni, vedere Limitazioni.
  • PrivilegeStatus.Allowed: l'API è supportata e consentita.

Metodo exportVisualsContent

Il metodo exportVisualsContent ha quattro parametri:

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

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

Metodo exportVisualsContentExtended

Anche il metodo exportVisualsContentExtended ha quattro parametri:

  • content: stringa
  • filename: stringa
  • fileType: string - Quando si esegue l'esportazione in un file .pdf o .xlsx, il parametro fileType 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 dei 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 nel servizio Power BI e Power BI Desktop
  • Il limite di dimensioni per un file scaricato è di 30 MB.
  • Questa API è un'API con privilegi.

Contenuto correlato