Share via

Dateidownload-API

  • Artikel

Mit der Dateidownload-API können Benutzer Daten aus einem benutzerdefinierten Visual in eine Datei auf ihrem Speichergerät herunterladen. Das Herunterladen eines Visuals erfordert die Einwilligung des Benutzers und eine Administratorberechtigung, die über den globalen Parameter „admin“ erteilt wird. Diese Einstellung ist unabhängig von den Downloadeinschränkungen, die in den Mandanteneinstellungen für Export und Freigabe der Organisation festgelegt sind, und wird von diesen nicht beeinflusst.

Screenshot der Administratoreinstellung, die das Herunterladen benutzerdefinierter Visuals ermöglicht.

Hinweis

Die Dateidownload-API umfasst drei Methoden:

  • exportVisualsContent ist ab der API-Version 4.5 verfügbar.
  • status ist ab der API-Version 4.6 verfügbar.
  • exportVisualsContentExtended ist ab der API-Version 5.3 verfügbar.
  • Um herauszufinden, welche Version Sie verwenden, überprüfen Sie die apiVersion in der Datei pbiviz.json.

Die Dateidownload-API ermöglicht den Export in Dateien der folgenden Typen:

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

Bevor der Download beginnt, wird ein Fenster angezeigt, in dem Sie bestätigen müssen, dass das Visual aus einer vertrauenswürdigen Quelle stammt.

Screenshot mit der Aufforderung, den Download nur zu bestätigen, wenn er aus einer vertrauenswürdigen Quelle stammt.

Verwenden der Dateidownload-API

Fügen Sie dem Berechtigungsarray in den Visualfunktionen eine Deklaration hinzu, um die Dateidownload-API zu verwenden.

Die Dateidownload-API umfasst drei Methoden:

Die beiden Methoden unterscheiden sich durch den Rückgabewert.

Die status -Methode

Die Statusmethode gibt den Status der Dateidownload-API zurück:

  • PrivilegeStatus.DisabledByAdmin: Die Administratoreinstellung für den Mandanten ist deaktiviert.
  • PrivilegeStatus.NotDeclared: Das Visual verfügt im Berechtigungsarray nicht über eine Deklaration für den lokalen Speicher.
  • PrivilegeStatus.NotSupported: Die API wird nicht unterstützt. Weitere Informationen finden Sie unter Einschränkungen.
  • PrivilegeStatus.Allowed: Die API wird unterstützt und ist zulässig.

Die exportVisualsContent -Methode

Die Methode exportVisualsContent verfügt über vier Parameter:

  • content: Zeichenfolge
  • filename: Zeichenfolge
  • fileType: Zeichenfolge. Beim Export in eine PDF- oder XLSX-Datei muss der fileType-Parameter base64 lauten.
  • fileDescription: Zeichenfolge

Diese Methode gibt eine Zusage zurück, die als boolescher Wert aufgelöst wird.

Die exportVisualsContentExtended -Methode

Die Methode exportVisualsContentExtended verfügt ebenfalls über vier Parameter:

  • content: Zeichenfolge
  • filename: Zeichenfolge
  • fileType: Zeichenfolge. Beim Export in eine PDF- oder XLSX-Datei muss der fileType-Parameter base64 lauten.
  • fileDescription: Zeichenfolge

Diese Methode gibt eine Zusage zurück, die in ein Ergebnis des Typs ExportContentResultInfo aufgelöst wird, das folgende Informationen enthält:

  • downloadCompleted: Angabe, ob der Download erfolgreich abgeschlossen wurde.
  • filename: der Name der exportierten Datei.

Beispiel: Dateidownload-API

Hier ist ein Beispiel, wie Sie den Inhalt eines benutzerdefinierten Visuals in eine Excel- und eine Textdatei herunterladen können.

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

Überlegungen und Einschränkungen

  • Die API wird nur im Power BI-Dienst und in Power BI Desktop unterstützt.
  • Das Größenlimit für eine heruntergeladene Datei beträgt 30 MB.
  • Diese API ist eine privilegierte API.

Zugehöriger Inhalt