Partager via

API de téléchargement de fichier

  • Article

L’API de téléchargement de fichier permet aux utilisateurs de télécharger des données à partir d’un visuel personnalisé dans un fichier sur leur appareil de stockage. Le téléchargement d’un visuel nécessite le consentement de l’utilisateur et l’autorisation de l’administrateur fournie dans le switch global d’administration. Ce paramètre est distinct et n’est pas affecté par les restrictions de téléchargement appliquées dans les paramètres Exportation et partage de votre locataire.

Capture d’écran du paramètre d’administration pour l’activation des téléchargements de visuel personnalisé.

Remarque

L’API de téléchargement de fichiers comporte trois méthodes :

  • exportVisualsContent est disponible à partir de la version 4.5 de l’API.
  • status est disponible à partir de la version 4.6 de l’API.
  • exportVisualsContentExtended est disponible à partir de la version 5.3 de l’API.
  • Pour savoir quelle version vous utilisez, consultez le apiVersion fichier pbiviz.json .

Utilisez l’API de téléchargement de fichiers pour exporter vers des fichiers des types suivants :

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

Avant le début du téléchargement, une fenêtre s’affiche et vous invite à confirmer que le visuel provient d’une source approuvée.

Capture d’écran vous demandant de ne confirmer le téléchargement que s’il provient d’une source approuvée.

Comment utiliser l’API de téléchargement de fichier

Pour utiliser l’API de téléchargement de fichiers, ajoutez une déclaration au tableau de privilèges dans les fonctionnalités des visuels.

L’API de téléchargement de fichiers comporte trois méthodes :

La différence entre les deux méthodes est la valeur de retour.

Méthode status

La méthode status retourne l’état de l’API de téléchargement de fichiers :

  • PrivilegeStatus.DisabledByAdmin : le commutateur d’administration du tenant est désactivé.
  • PrivilegeStatus.NotDeclared : le visuel n’est pas lié à une déclaration de stockage local dans le tableau de privilèges.
  • PrivilegeStatus.NotSupported : l’API n’est pas prise en charge. Consultez les limitations pour en savoir plus.
  • PrivilegeStatus.Allowed : l’API est prise en charge et autorisée.

Méthode exportVisualsContent

La méthode exportVisualsContent a quatre paramètres :

  • content : chaîne
  • filename : chaîne
  • fileType : chaîne ; lors de l’exportation vers un fichier .pdf ou .xlsx, le paramètre fileType doit être base64
  • fileDescription : chaîne

Cette méthode retourne une promesse qui sera résolue en valeur booléenne.

Méthode exportVisualsContentExtended

La méthode exportVisualsContentExtended a aussi quatre paramètres :

  • content : chaîne
  • filename : chaîne
  • fileType : chaîne ; lors de l’exportation vers un fichier .pdf ou .xlsx, le paramètre fileType doit être base64
  • fileDescription : chaîne

Cette méthode retourne une promesse qui sera résolue avec un résultat de type ExportContentResultInfo qui contient les paramètres suivants :

  • downloadCompleted : si le téléchargement s’est terminé avec succès.
  • filename : nom du fichier exporté.

Exemple : API de téléchargement de fichier

Voici un exemple de téléchargement du contenu d’un visuel personnalisé dans un fichier Excel et un fichier texte.

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

Considérations et limitations

  • L’API est prise en charge uniquement dans le service Power BI et Power BI Desktop
  • La limite de taille d’un fichier téléchargé est de 30 Mo.
  • Cette API est une API privilégiée.

Contenu connexe