Dateidownload-API
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.
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
- .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.
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:
- status: ist ab der API-Version 4.6 verfügbar.
exportVisualsContent
: ab API-Version 4.5 verfügbarexportVisualsContentExtended
: ab API-Version 5.3 verfügbar
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
-Parameterbase64
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
-Parameterbase64
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.