通过

文件下载 API

  • 项目

通过文件下载 API，用户可以将数据从自定义视觉对象下载到其存储设备上的文件中。 下载视觉对象需要用户同意和管理员全局开关中提供的管理员权限。 此设置独立于组织的“导出和共享”租户设置中应用的下载限制且不受其影响。

允许自定义视觉对象下载的管理设置的屏幕截图。

注意

文件下载 API 提供三种方法：

使用文件下载 API 导出到以下类型的文件：

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

在下载开始之前会弹出一个窗口，要求确认视觉对象是否来自受信任的源。

要求确认下载的屏幕截图，只有当数据来自受信任的源时才可以下载。

如何使用文件下载 API

要使用文件下载 API，请向视觉功能中的特权数组添加声明。

文件下载 API 提供三种方法：

这两种方法的区别在于返回值。

status 方法

status 方法返回文件下载 API 的状态：

  • PrivilegeStatus.DisabledByAdmin：租户管理员开关已关闭
  • PrivilegeStatus.NotDeclared：视觉对象在特权数组中没有本地存储的声明
  • PrivilegeStatus.NotSupported：不支持该 API。 有关详细信息，请参阅限制。
  • PrivilegeStatus.Allowed：支持并允许使用该 API。

exportVisualsContent 方法

exportVisualsContent 方法具有四个参数：

  • content: string
  • filename: string
  • fileType: string - 导出到 .pdf 或 .xlsx 文件时，fileType 参数应为 base64
  • fileDescription: string

此方法返回一个将针对布尔值解析的承诺。

exportVisualsContentExtended 方法

exportVisualsContentExtended 方法也有四个参数：

  • content: string
  • filename: string
  • fileType: string - 导出到 .pdf 或 .xlsx 文件时，fileType 参数应为 base64
  • fileDescription: string

此方法返回一个承诺，该承诺将使用类型为 ExportContentResultInfo 的结果解析，其中包含以下参数：

  • downloadCompleted - 如果下载已成功完成。
  • filename - 导出的文件名。

示例：文件下载 API

下面是如何将自定义视觉对象的内容下载到 Excel 文件和文本文件中的示例。

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

注意事项和限制

  • API 仅在 Power BI 服务 和 Power BI Desktop 中受支持
  • 已下载文件的大小限制为 30 MB。
  • 此 API 是特权 API。

相关内容