Compartir a través de

API de descarga de archivos

  • Artículo

La API de descarga de archivos permite a los usuarios descargar datos de un objeto visual personalizado en un archivo en su dispositivo de almacenamiento. La descarga de un objeto visual requiere el consentimiento del usuario y el permiso de administrador proporcionados en el modificador global de administración. Esta opción de configuración es independiente de las restricciones de descarga aplicadas en la configuración de exportación y uso compartido del inquilino de la organización, que no le afectan.

Captura de pantalla de la configuración de administrador habilitando las descargas de objeto visual personalizado.

Nota:

La API de descarga de archivos tiene tres métodos:

  • exportVisualsContent está disponible desde la versión 4.5 de la API.
  • status está disponible desde la versión 4.6 de la API.
  • exportVisualsContentExtended está disponible desde la versión 5.3 de la API.
  • Para averiguar qué versión usa, compruebe apiVersion en el archivo pbiviz.json.

Use la API de descarga de archivos para exportar a archivos de los siguientes tipos:

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

Antes de que comience la descarga, aparece una ventana que solicita confirmar que la imagen proviene de una fuente confiable.

Captura de pantalla en la que se pide la confirmación de la descarga solo si procede de un origen de confianza.

Uso de la API de descarga de archivos

Para usar la API de descarga de archivos agregue una declaración a la matriz de privilegios en las funcionalidades visuales.

La API de descarga de archivos tiene tres métodos:

La diferencia entre los dos métodos es el valor devuelto.

El método status

El método de estado devuelve el estado de la API de descarga de archivos:

  • PrivilegeStatus.DisabledByAdmin: el modificador de administrador de inquilinos está desactivado
  • PrivilegeStatus.NotDeclared: el objeto visual no tiene ninguna declaración para el almacenamiento local en la matriz de privilegios
  • PrivilegeStatus.NotSupported: no se admite la API. Para más información, consulte las limitaciones.
  • PrivilegeStatus.Allowed: la API se admite y se permite.

El método exportVisualsContent

El método exportVisualsContent tiene cuatro parámetros:

  • content: cadena
  • filename: cadena
  • fileType: cadena: al exportar a un archivo .pdf o .xlsx, el parámetro fileType debería ser base64
  • fileDescription: cadena

Este método devuelve una promesa que se resuelve como un valor booleano.

El método exportVisualsContentExtended

El método exportVisualsContentExtended tiene cuatro parámetros:

  • content: cadena
  • filename: cadena
  • fileType: cadena: al exportar a un archivo .pdf o .xlsx, el parámetro fileType debería ser base64
  • fileDescription: cadena

Este método devuelve una promesa, que se resolverá con un resultado de tipo ExportContentResultInfo que contiene los parámetros siguientes:

  • downloadCompleted: si la descarga se ha completado correctamente.
  • filename: nombre del archivo exportado.

Ejemplo: API de descarga de archivos

Este es un ejemplo de cómo descargar el contenido de un objeto visual personalizado en un archivo de Excel y un archivo de texto.

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

Consideraciones y limitaciones

  • La API solo se admite en el servicio Power BI y Power BI Desktop
  • El límite de tamaño de un archivo descargado es de 30 MB.
  • Esta API es una API con privilegios.

Contenido relacionado