Exporter un rapport paginé dans un fichier
L’API exportToFile permet d’exporter un rapport paginé Power BI avec un appel REST. Les formats de fichier suivants sont pris en charge :
.pptx (PowerPoint)
.pdf (et PDF accessible, ou PDF/UA)
.xlsx (Excel)
.docx (Word)
.csv
.xml
.mhtml
Image
Lors de l’exportation vers une image, définissez le format de l’image par le biais du paramètre de formatOutputFormat. Les valeurs prises en charge pourOutputFormatsont les suivantes :- .tiff (par défaut)
- .bmp
- .emf
- .gif
- .jpeg
- .png
Exemples d'utilisation
Vous pouvez utiliser la fonction d’exportation de diverses 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 paramètres de rapport et de paramètres de format, vous pouvez exporter le rapport dans un état spécifique, y compris les données filtrées, les tailles de pages personnalisées et d’autres paramètres propres au format. É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.
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
exportToFileoffre une prise en charge limitée dans Premium par utilisateur (PPU).
É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é.
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
Paramètres de format
Spécifiez divers paramètres de format pour chaque format de fichier. Les propriétés et les valeurs prises en charge sont équivalentes aux paramètres Informations sur l’appareil pour les paramètres d’URL de rapport paginé.
Voici deux exemples. Le premier exemple permet d’exporter les quatre premières pages d’un rapport en utilisant la taille de page du rapport vers un fichier .pptx. Le deuxième exemple concerne l’exportation de la troisième page d’un rapport vers un fichier .jpeg.
Exportation des quatre premières pages dans un fichier .pptx
{
"format": "PPTX",
"paginatedReportConfiguration":{
"formatSettings":{
"UseReportPageSize": "true",
"StartPage": "1",
"EndPage": "4"
}
}
}
Exportation de la troisième page dans un fichier .jpeg
{
"format": "IMAGE",
"paginatedReportConfiguration":{
"formatSettings":{
"OutputFormat": "JPEG",
"StartPage": "3",
"EndPage": "3"
}
}
}
Paramètres de rapport
Vous pouvez utiliser l’API exportToFile pour exporter par programmation un rapport avec un jeu de paramètres de rapport. Cette opération s’effectue à l’aide des fonctionnalités de paramètre de rapport.
Voici un exemple de définition de valeurs de paramètre de rapport.
{
"format": "PDF",
"paginatedReportConfiguration":{
"parameterValues":[
{"name": "State", "value": "WA"},
{"name": "City", "value": "Seattle"},
{"name": "City", "value": "Bellevue"},
{"name": "City", "value": "Redmond"}
]
}
}
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)
Quand vous utilisez un modèle sémantique Power BI ayant la sécurité au niveau des lignes (SNL) définie comme source de données, vous pouvez exporter un rapport qui affiche uniquement les données visibles par 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 à l’aide de la sécurité au niveau des lignes, vous devez disposer de l’autorisation de lecture sur le modèle sémantique Power BI que le rapport utilise comme source de données.
Voici un exemple de spécification d’un nom d’utilisateur effectif pour la sécurité au niveau des lignes.
{
"format": "PDF",
"paginatedReportConfiguration":{
"identities": [
{"username": "john@contoso.com"}
]
}
}
Authentification unique SQL et Dataverse (SSO)
Dans Power BI, vous avez la possibilité de définir OAuth avec SSO. Dans ce cas, les informations d’identification de l’utilisateur qui consulte le rapport servent à récupérer les données. Le jeton d’accès dans l’en-tête de la demande n’est pas utilisé pour accéder aux données. Le jeton doit être transmis avec l’identité effective dans le corps du message.
Obtenir le jeton d’accès correct pour la ressource à laquelle vous voulez accéder peut parfois s’avérer délicat.
- Pour Azure SQL, la ressource est
https://database.windows.net. - Pour Dataverse, la ressource est l’adresse
https://de votre environnement. Par exemple :https://contoso.crm.dynamics.com.
Accédez à l’API du jeton à l’aide de la méthode AuthenticationContext.AcquireTokenAsync.
Voici un exemple pour fournir une identité effective (nom d’utilisateur) avec un jeton d’accès.
{
"format":"PDF",
"paginatedReportConfiguration":{
"formatSettings":{
"AccessiblePDF":"true",
"PageHeight":"11in",
"PageWidth":"8.5in",
"MarginBottom":"2in"
},
"identities":[
{
"username":"john@contoso.com",
"identityBlob": {
"value": "eyJ0eX....full access token"
}
}
]
}
}
Demandes simultanées
exportToFile prend en charge un nombre limité de requêtes simultanées. Le nombre maximal de requêtes simultanées d'affichage de rapport paginé est de 500. 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.
Avec l’utilisation de Premium par utilisateur (PPU), l’API exportToFilen’autorise qu’une seule requête dans une fenêtre de cinq minutes. Plusieurs requêtes dans une fenêtre de cinq minutes entraînent une erreur de type Nombre de requêtes trop élevé (429).
Exemples de code
Vous pouvez télécharger le SDK d’API Power BI utilisé dans les exemples de code ici.
Lorsque vous créez un travail d’exportation, il y a trois étapes à suivre :
- Envoi d’une demande d’exportation.
- Interrogation.
- Obtention du 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 des valeurs de paramètres de plage de pages, de taille et de rapport spécifiques.
private async Task<string> PostExportRequest(
Guid reportId,
Guid groupId)
{
// For documentation purposes the export configuration is created in this method
// Ordinarily, it would be created outside and passed in
var paginatedReportExportConfiguration = new PaginatedReportExportConfiguration()
{
FormatSettings = new Dictionary<string, string>()
{
{"PageHeight", "14in"},
{"PageWidth", "8.5in" },
{"StartPage", "1"},
{"EndPage", "4"},
},
ParameterValues = new List<ParameterValue>()
{
{ new ParameterValue() {Name = "State", Value = "WA"} },
{ new ParameterValue() {Name = "City", Value = "Redmond"} },
},
};
var exportRequest = new ExportReportRequest
{
Format = FileFormat.PDF,
PaginatedReportExportConfiguration = paginatedReportExportConfiguration,
};
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 demande de rapport, utilisez l’interrogation pour savoir quand le fichier exporté que vous attendez est prêt.
private async Task<Export> PollExportRequest(
Guid reportId,
Guid groupId,
string exportId /* Get from the ExportToAsync response */,
int timeOutInMinutes,
CancellationToken token)
{
Export exportStatus = null;
DateTime startTime = DateTime.UtcNow;
const int secToMillisec = 1000;
do
{
if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes || token.IsCancellationRequested)
{
// Error handling for timeout and cancellations
return null;
}
var httpMessage =
await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId, exportId);
exportStatus = httpMessage.Body;
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 only populated when the status is either Running or NotStarted
var retryAfter = httpMessage.Response.Headers.RetryAfter;
var retryAfterInSec = retryAfter.Delta.Value.Seconds;
await Task.Delay(retryAfterInSec * secToMillisec);
}
}
// While not in a terminal state, keep polling
while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);
return exportStatus;
}
É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 GetExportStatusAsync response */)
{
if (export.Status == ExportState.Succeeded)
{
var httpMessage =
await Client.Reports.GetFileOfExportToFileInGroupWithHttpMessagesAsync(groupId, reportId, export.Id);
return new ExportedFile
{
FileStream = httpMessage.Body,
ReportName = export.ReportName,
FileExtension = export.ResourceFileExtension,
};
}
return null;
}
public class ExportedFile
{
public Stream FileStream;
public string ReportName;
public string FileExtension;
}
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 :
private async Task<ExportedFile> ExportPaginatedReport(
Guid reportId,
Guid groupId,
int pollingtimeOutInMinutes,
CancellationToken token)
{
try
{
var exportId = await PostExportRequest(reportId, groupId);
var export = await PollExportRequest(reportId, groupId, exportId, pollingtimeOutInMinutes, token);
if (export == null || export.Status != ExportState.Succeeded)
{
// Error, failure in exporting the report
return null;
}
return await GetExportedFile(reportId, groupId, export);
}
catch
{
// Error handling
throw;
}
}
Considérations et limitations
L'exportation d'un rapport paginé dont la source de données est un modèle sémantique Power BI n'est pas prise en charge dans les cas suivants :
- L’appelant est un profil de principal de service.
- L’une des sources de données du modèle sémantique est configurée avec l’authentification unique activée et une identité effective a été fournie.
- Le modèle sémantique Power BI dispose de DirectQuery pour Azure Analysis Services ou pour un autre modèle sémantique Power BI, et une identité efficace a été fournie.
L’exportation d’un rapport paginé qui a Azure Analysis Services source de données configurée avec l’authentification unique activée n’est pas prise en charge dans les cas suivants :
- L’appelant est un profil de principal de service.
- L’appelant est un utilisateur maître et une identité efficace a été fournie.
Pour exporter un rapport paginé avec une identité effective, le nom d’utilisateur doit correspondre à un utilisateur existant dans Microsoft Entra ID de votre locataire.
L’exportation d’un rapport est limitée à 60 minutes, ce qui correspond à la durée de vie du jeton d’accès utilisateur. Si vous recevez une erreur d’expiration de délai au-delà de la 60e minute lors de l’exportation de grandes quantités de données, songez à réduire la quantité de données en utilisant des filtres appropriés.
Le lien hypertexte d’URL du partage de fichiers (chemin d’accès /UNC du partage de fichiers) ne fonctionne pas lors de l’exportation d’un rapport paginé publié sur service Power BI en ligne.
Contenu connexe
Vérifiez comment incorporer du contenu pour vos clients et votre organisation :