共用方式為

檔案下載 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：字串
  • filename：字串
  • fileType：string - 匯出成 .pdf 或 .xlsx 檔案時，fileType 參數應該是 base64
  • fileDescription：字串

這個方法會傳回將針對布林值解析的承諾。

exportVisualsContentExtended 方法

exportVisualsContentExtended 方法也有四個參數：

  • content：字串
  • filename：字串
  • fileType：string - 匯出成 .pdf 或 .xlsx 檔案時，fileType 參數應該是 base64
  • fileDescription：字串

這個方法會傳回承諾，其會以包含下列參數的 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。

相關內容