Exporter un rapport Power BI vers un fichier

Article
12/19/2023

L’API exportToFile permet d’exporter un rapport Power BI avec un appel REST. Les formats de fichier suivants sont pris en charge :

.pptx (PowerPoint)
.pdf
.png
- Lors de l’exportation vers un fichier .png, un rapport de plusieurs pages est comprimé dans un fichier .zip
- Chaque fichier contenu dans le fichier .zip représente une page du rapport
- Les noms des pages sont les mêmes que les valeurs de retour des API Obtenir des pages ou Obtenir des pages dans le groupe

Remarque

L’exportation d’un rapport Power BI vers un fichier à l’aide de l’API exportToFile n’est pas prise en charge pour Premium par utilisateur (PPU).

Exemples d'utilisation

Vous pouvez utiliser la fonction d’exportation de plusieurs façons. Voici quelques exemples :

Bouton Envoyer à l’impression : dans votre application, créez un bouton qui, lorsque vous cliquez dessus, déclenche un travail d’exportation. Le travail peut exporter le rapport consulté au format .pdf ou .pptx. Lorsqu’il est terminé, l’utilisateur peut recevoir le fichier sous forme de téléchargement. À l’aide de signets, vous pouvez exporter le rapport dans un état spécifique, y compris des filtres configurés, des segments et d’autres paramètres. Étant donné que l’API est asynchrone, la mise à disposition du fichier peut prendre un certain temps.
Pièce jointe d’e-mail : envoyer un e-mail automatisé à intervalles définis, avec un rapport .pdf en pièce jointe. Ce scénario peut être utile si vous souhaitez automatiser l’envoi d’un rapport hebdomadaire aux dirigeants. Pour plus d’informations, consultez Exportation et envoi par e-mail d’un rapport Power BI avec Power Automate

Utilisation de l’API

Conditions de licence :

Le rapport que vous exportez doit résider dans un espace de travail soutenu par une capacité Premium, Embedded ou Fabric.
L’API exportToFile n’est pas prise en charge pour Premium par utilisateur (PPU).

Paramètres d’administration

Avant d’utiliser l’API, vérifiez que les paramètres de locataire administrateurs suivants sont activés :

Exporter les rapports comme présentations PowerPoint ou documents PDF : activé par défaut.
Exporter des rapports en tant que fichiers image : nécessaire uniquement pour les fichiers .png, et désactivé par défaut.

Événements de « rendu »

Pour que l’exportation ne commence pas avant la fin du rendu du visuel, utilisez l’API des événements « Rendu » et commencez l’exportation seulement une fois le rendu terminé.

Interrogation

L’API est asynchrone. Lorsque l’API exportToFile est appelée, elle déclenche un travail d’exportation. Après avoir déclenché un travail d’exportation, utilisez l’interrogation pour suivre le travail jusqu’à ce qu’il soit terminé.

Pendant l’interrogation, l’API retourne un nombre qui représente la quantité de travail effectué. Les tâches dans chaque travail d’exportation sont calculées en fonction du nombre total d’exportations dans le travail. Une exportation comprend l’exportation d’un seul visuel ou d’une page avec ou sans signets. Toutes les exportations ont le même poids. Si, par exemple, votre travail d’exportation inclut l’exportation d’un rapport de 10 pages et que l’interrogation retourne 70, cela signifie que l’API a traité sept des 10 pages du travail d’exportation.

Une fois l’exportation terminée, l’appel de l’API d’interrogation retourne une URL Power BI pour obtenir le fichier. L’URL est disponible pendant 24 heures.

Fonctionnalités prises en charge

Cette section décrit l’utilisation des fonctionnalités prises en charge suivantes :

Sélection des pages à imprimer
Exportation d’une page ou d’un seul visuel
Signets
Filtres
Authentification
Sécurité au niveau de la ligne (RLS)
Protection des données
Localisation
Liaison dynamique

Sélection des pages à imprimer

Spécifiez les pages à imprimer en fonction de la valeur de retour Obtenir des pages ou Obtenir des pages dans le groupe. Vous pouvez également spécifier l’ordre des pages que vous exportez.

Exportation d’une page ou d’un seul visuel

Vous pouvez spécifier une page ou un visuel unique à exporter. Les pages peuvent être exportées avec ou sans signets.

Selon le type d’exportation, vous devez passer différents attributs à l’objet ExportReportPage. Le tableau suivant spécifie les attributs nécessaires pour chaque travail d’exportation.

Remarque

L’exportation d’un seul visuel a le même poids que l’exportation d’une page (avec ou sans signets). Cela signifie que, en termes de calculs système, les deux opérations ont la même valeur.

Attribut	Page	Commentaires
`bookmark`	Facultatif	Utilisez cet attribut pour exporter une page dans un état spécifique.
`pageName`		Utilisez l’API REST GetPages ou l’API client `getPages`.
`visualName`		Il existe deux façons d’obtenir le nom du visuel : Utilisez l’API client `getVisuals`. Écoutez et journalisez l’événement visualClicked, qui se déclenche quand un visuel est sélectionné. Pour plus d’informations, consultez Comment gérer des événements. .

Signets

Des signets peuvent être utilisés pour enregistrer un rapport dans une configuration spécifique, y compris avec des filtres appliqués et l’état des visuels du rapport. Vous pouvez utiliser l’API exportToFile pour exporter par programme le signet d’un rapport, de deux manières :

Exporter un signet existant

Pour exporter un signet de rapport existant, utilisez la propriété name, un identificateur unique (sensible à la casse) que vous pouvez obtenir à l’aide de l’API de signets JavaScript.
Exporter l’état du rapport

Pour exporter l’état actuel du rapport, utilisez la propriété state. Par exemple, vous pouvez utiliser la méthode de signet bookmarksManager.capture pour capturer les modifications apportées par un utilisateur spécifique à un rapport, puis l’exporter dans son état actuel avec capturedBookmark.state.

Notes

Les signets personnels et les filtres persistants ne sont pas pris en charge.

Filtres

Dans PowerBIReportExportConfiguration, reportLevelFilters permet d’exporter un rapport filtré.

Pour exporter un rapport filtré, insérez dans ExportFilter les paramètres de chaîne de requête d’URL que vous souhaitez utiliser comme filtre. Lorsque vous entrez la chaîne, vous devez supprimer la partie ?filter= du paramètre de requête d’URL.

Le tableau contient quelques exemples de syntaxe de chaînes que vous pouvez passer à ExportFilter.

Filtrer	Syntaxe	Exemple
Valeur dans un champ	Table/Champ eq ’valeur’	Store/Territory eq ’NC’
Plusieurs valeurs dans un champ	Table/Champ in (’valeur1’, ’valeur2’)	Store/Territory in (’NC’, ’TN’)
Valeur distincte dans un champ, autre valeur distincte dans un autre champ	Table/Champ1 eq ’valeur1’ and Table/Champ2 eq ’valeur2’	Store/Territory eq ’NC’ and Store/Chain eq ’Fashions Direct’

Authentification

Vous pouvez vous authentifier avec un utilisateur (ou un utilisateur maître) ou un principal de service.

Sécurité au niveau de la ligne (RLS)

La Sécurité au niveau de la ligne (RLS) permet d’exporter un rapport mentionnant des données qui ne sont accessibles qu’à certains utilisateurs. Par exemple, si vous exportez un rapport de ventes défini avec des rôles régionaux, vous pouvez filtrer programmatiquement le rapport de façon à n’afficher qu’une région précise.

Pour exporter avec RLS, vous devez disposer des autorisations suivantes :

Écrire et partager à nouveau des autorisations pour le modèle sémantique auquel le rapport est connecté
Membre ou administrateur de l’espace de travail où réside le rapport

Protection des données

Les formats .pdf et .pptx prennent en charge les étiquettes de sensibilité. Si vous exportez un rapport doté d’une étiquette de sensibilité au format .pdf ou .pptx, le fichier exporté affiche le rapport avec son étiquette de sensibilité.

Un rapport avec une étiquette de sensibilité ne peut pas être exporté au format .pdf ou .pptx à l’aide d’un principal de service.

Localisation

Lorsque vous utilisez l’API exportToFile, vous pouvez transmettre les paramètres régionaux souhaités. Les paramètres de localisation affectent la façon dont le rapport est affiché, par exemple en modifiant la mise en forme en fonction de la valeur locale sélectionnée.

Liaison dynamique

Pour exporter un rapport connecté à un modèle sémantique autre que le modèle sémantique par défaut, spécifiez l’ID de modèle sémantique requis dans le paramètre datasetToBind lors de l’appel de l’API. En savoir plus sur la liaison dynamique.

Demandes simultanées

L’API exportToFile prend en charge un nombre limité de demandes simultanées. Le nombre maximal de requêtes simultanées pris en charge est de 500 par capacité. Pour éviter un dépassement de limite et recevoir une erreur Nombre de requêtes trop élevé (429), répartissez la charge sur la durée ou à travers les capacités. Seules cinq pages d’un rapport sont traitées simultanément. Par exemple, si vous exportez un rapport de 50 pages, la tâche d’exportation est traitée en 10 intervalles séquentiels. Lorsque vous optimisez votre tâche d’exportation, vous pouvez envisager d’exécuter plusieurs tâches en parallèle.

Exemples de code

Lorsque vous créez un travail d’exportation, il y a quatre étapes à suivre :

Envoi d’une demande d’exportation.
Interrogation.
Obtention du fichier.
Utilisation du flux de fichier.

Cette section fournit des exemples pour chaque étape.

Étape 1 : envoi d’une demande d’exportation

La première étape consiste à envoyer une demande de rapport. Dans cet exemple, une demande d’exportation est envoyée pour une page spécifique.

private async Task<string> PostExportRequest(
    Guid reportId,
    Guid groupId,
    FileFormat format,
    IList<string> pageNames = null, /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
    var powerBIReportExportConfiguration = new PowerBIReportExportConfiguration
    {
        Settings = new ExportReportSettings
        {
            Locale = "en-us",
        },
        // Note that page names differ from the page display names
        // To get the page names use the GetPages REST API
        Pages = pageNames?.Select(pn => new ExportReportPage(Name = pn)).ToList(),
        // ReportLevelFilters collection needs to be instantiated explicitly
        ReportLevelFilters = !string.IsNullOrEmpty(urlFilter) ? new List<ExportFilter>() { new ExportFilter(urlFilter) } : null,

    };

    var exportRequest = new ExportReportRequest
    {
        Format = format,
        PowerBIReportConfiguration = powerBIReportExportConfiguration,
    };

    // The 'Client' object is an instance of the Power BI .NET SDK
    var export = await Client.Reports.ExportToFileInGroupAsync(groupId, reportId, exportRequest);

    // Save the export ID, you'll need it for polling and getting the exported file
    return export.Id;
}

Étape 2 : interrogation

Après avoir envoyé une requête de rapport, utilisez l’interrogation pour savoir quand le fichier exporté que vous attendez est prêt.

private async Task<HttpOperationResponse<Export>> PollExportRequest(
    Guid reportId,
    Guid groupId,
    string exportId /* Get from the PostExportRequest response */,
    int timeOutInMinutes,
    CancellationToken token)
{
    HttpOperationResponse<Export> httpMessage = null;
    Export exportStatus = null;
    DateTime startTime = DateTime.UtcNow;
    const int c_secToMillisec = 1000;
    do
    {
        if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes || token.IsCancellationRequested)
        {
            // Error handling for timeout and cancellations 
            return null;
        }

        // The 'Client' object is an instance of the Power BI .NET SDK
        httpMessage = await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId, exportId);
        exportStatus = httpMessage.Body;

        // You can track the export progress using the PercentComplete that's part of the response
        SomeTextBox.Text = string.Format("{0} (Percent Complete : {1}%)", exportStatus.Status.ToString(), exportStatus.PercentComplete);
        if (exportStatus.Status == ExportState.Running || exportStatus.Status == ExportState.NotStarted)
        {
            // The recommended waiting time between polling requests can be found in the RetryAfter header
            // Note that this header is not always populated
            var retryAfter = httpMessage.Response.Headers.RetryAfter;
            var retryAfterInSec = retryAfter.Delta.Value.Seconds;
            await Task.Delay(retryAfterInSec * c_secToMillisec);
        }
    }
    // While not in a terminal state, keep polling
    while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);

    return httpMessage;
}

Étape 3 : obtention du fichier

Une fois que l’interrogation retourne une URL, utilisez cet exemple pour accéder au fichier reçu.

private async Task<ExportedFile> GetExportedFile(
    Guid reportId,
    Guid groupId,
    Export export /* Get from the PollExportRequest response */)
{
    if (export.Status == ExportState.Succeeded)
    {
        // The 'Client' object is an instance of the Power BI .NET SDK
        var fileStream = await Client.Reports.GetFileOfExportToFileAsync(groupId, reportId, export.Id);
        return new ExportedFile
        {
            FileStream = fileStream,
            FileSuffix = export.ResourceFileExtension,
        };
    }
    return null;
}

public class ExportedFile
{
    public Stream FileStream;
    public string FileSuffix;
}

Étape 4 : Utilisation du flux de fichier

Une fois que vous avez le flux de fichier, vous pouvez le gérer selon vos besoins. Par exemple, vous pouvez l’envoyer par e-mail ou l’utiliser pour télécharger les rapports exportés.

Exemple de bout en bout

Il s’agit d’un exemple de bout en bout pour l’exportation d’un rapport. Il comprend les étapes suivantes :

Envoi de la demande d'exportation.
Interrogation.
Obtention du fichier.

private async Task<ExportedFile> ExportPowerBIReport(
	Guid reportId,
	Guid groupId,
	FileFormat format,
	int pollingtimeOutInMinutes,
	CancellationToken token,
	IList<string> pageNames = null,  /* Get the page names from the GetPages REST API */
    string urlFilter = null)
{
	const int c_maxNumberOfRetries = 3; /* Can be set to any desired number */
	const int c_secToMillisec = 1000;
	try
	{
		Export export = null;
		int retryAttempt = 1;
		do
		{
			var exportId = await PostExportRequest(reportId, groupId, format, pageNames, urlFilter);
			var httpMessage = await PollExportRequest(reportId, groupId, exportId, pollingtimeOutInMinutes, token);
			export = httpMessage.Body;
			if (export == null)
			{
				// Error, failure in exporting the report
				return null;
			}
			if (export.Status == ExportState.Failed)
			{
				// Some failure cases indicate that the system is currently busy. The entire export operation can be retried after a certain delay
				// In such cases the recommended waiting time before retrying the entire export operation can be found in the RetryAfter header
				var retryAfter = httpMessage.Response.Headers.RetryAfter;
				if(retryAfter == null)
				{
				    // Failed state with no RetryAfter header indicates that the export failed permanently
				    return null;
                }

                var retryAfterInSec = retryAfter.Delta.Value.Seconds;
                await Task.Delay(retryAfterInSec * c_secToMillisec);
            }
        }
        while (export.Status != ExportState.Succeeded && retryAttempt++ < c_maxNumberOfRetries);

        if (export.Status != ExportState.Succeeded)
        {
            // Error, failure in exporting the report
            return null;
        }

        var exportedFile = await GetExportedFile(reportId, groupId, export);

        // Now you have the exported file stream ready to be used according to your specific needs
        // For example, saving the file can be done as follows:
        /*
            var pathOnDisk = @"C:\temp\" + export.ReportName + exportedFile.FileSuffix;

            using (var fileStream = File.Create(pathOnDisk))
            {
                exportedFile.FileStream.CopyTo(fileStream);
            }
        */

        return exportedFile;
    }
    catch
    {
        // Error handling
        throw;
    }
}

Observations et limitations

Le chargement d’une opération d’API d’exportation est évalué en tant qu’opération en arrière-plan lente, comme décrit dans Évaluation du chargement de la capacité Premium.
Tous les modèles sémantiques associés dans le rapport que vous exportez doivent résider sur une capacité Premium ou Incorporée, y compris les modèles sémantiques avec une connexion DirectQuery.
Les rapports exportés ne peuvent pas dépasser une taille de fichier de 250 Mo.
Lors de l’exportation en tant que fichier .png, les étiquettes de sensibilité ne sont pas prises en charge.
Le nombre d’exportations (visuels uniques ou pages de rapport) pouvant être inclus dans un même rapport exporté s’élève à 50 (l’exportation de rapports paginés est exclue). Si la demande inclut d’autres exportations, l’API retourne une erreur et le travail d’exportation est annulé.
Les signets personnels et les filtres persistants ne sont pas pris en charge pour l’exportation de rapports Power BI dans un fichier.
L’API exportToFile exporte le rapport avec la valeur par défaut s’il est utilisé sans signets ou reportLevelFilters.
Les visuels Power BI répertoriés ici ne sont pas pris en charge. Lorsqu’un rapport contenant ces visuels est exporté, les parties du rapport contenant ces visuels ne sont pas rendues et un symbole d’erreur s’affiche.
- Visuels personnalisés Power BI non certifiés
- Visuels R
- PowerApps
- Visuels Python
- Power Automate
- Visuel de rapport paginé
- Visio
- Visuels ArcGIS

Vérifiez comment incorporer du contenu pour vos clients et votre organisation :

D’autres questions ? Essayez la communauté Power BI.