파일 다운로드 API

파일 다운로드 API를 사용하면 사용자가 사용자 지정 시각적 개체의 데이터를 스토리지 디바이스의 파일로 다운로드할 수 있습니다. 시각적 개체를 다운로드하려면 사용자 동의 및 관리자 전역 스위치에 제공된 관리자 권한이 필요합니다. 이 설정은 조직의 내보내기 및 공유 테넌트 설정에 적용되는 다운로드 제한 사항과 별개이며 영향을 받지 않습니다.

참고 항목

파일 다운로드 API에는 세 가지 메서드가 있습니다.

• exportVisualsContent은(는) API 버전 4.5에서 사용할 수 있습니다.
• status는 API 버전 4.6에서 사용할 수 있습니다.
• exportVisualsContentExtended은(는) API 버전 5.3에서 사용할 수 있습니다.
• 사용 중인 버전을 확인하려면 pbiviz.json 파일에서 apiVersion을 확인합니다.

파일 다운로드 API는 다음 형식의 파일로 내보낼 수 있습니다.

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

다운로드가 시작되기 전에 시각적 개체가 신뢰할 수 있는 원본에서 온 것인지 확인하는 창이 나타납니다.

파일 다운로드 API를 사용하는 방법

파일 다운로드 API를 사용하려면 시각적 기능의 권한 배열에 선언을 추가합니다.

파일 다운로드 API에는 세 가지 메서드가 있습니다.

• 상태: API 버전 4.6부터 사용 가능
• exportVisualsContent: API 버전 4.5에서 사용할 수 있습니다.
• exportVisualsContentExtended: API 버전 5.3에서 사용할 수 있습니다.

두 메서드의 차이점은 반환 값입니다.

status 메서드

상태 메서드는 파일 다운로드 API의 상태를 반환합니다.

• PrivilegeStatus.DisabledByAdmin: 테넌트 관리자 스위치가 꺼져 있습니다.
• Privileged Status.Not Declared: 시각적 개체에는 권한 배열의 로컬 스토리지에 대한 선언이 없습니다.
• PrivilegeStatus.NotSupported: API가 지원되지 않습니다. 자세한 내용은 제한 사항을 참조하세요.
• PrivilegeStatus.Allowed: API가 지원되고 허용됩니다.

exportVisualsContent 메서드

exportVisualsContent 메서드는 네 개의 매개 변수가 있습니다.

• 콘텐츠: 문자열
• filename: 문자열
• fileType: 문자열 - .pdf 또는 .xlsx 파일로 내보낼 때 fileType 매개 변수는 base64가 되어야 합니다.
• fileDescription: 문자열

이 메서드는 부울 값에 대해 확인되는 프라미스를 반환합니다.

exportVisualsContentExtended 메서드

exportVisualsContentExtended 메서드에는 다음 네 개의 매개 변수도 있습니다.

• 콘텐츠: 문자열
• filename: 문자열
• fileType: 문자열 - .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 데스크톱에서만 지원됩니다.
• 다운로드한 파일 크기 제한은 30MB입니다.
• 이 API는 권한 있는 API입니다.

관련 콘텐츠

• Visual API에 대해 알아보기

• Power BI 시각적 개체 인증받기