Exporter un rapport paginé dans un fichier
L’API exportToFile permet d’exporter un rapport paginé Power BI à l’aide d’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 via le paramètre de formatOutputFormat. Les valeurs deOutputFormatprises en charge sont les suivantes :- .tiff (par défaut)
- .bmp
- .emf
- .gif
- .jpeg
- .png
Exemples d’utilisation
Vous pouvez utiliser la fonctionnalité d’exportation de différentes façons. Voici quelques exemples :
bouton Envoyer à l’impression - Dans votre application, créez un bouton qui, lorsqu'on clique dessus, déclenche un travail d'exportation. Le travail peut exporter le rapport consulté au format .pdf ou .pptx. Une fois l’opération terminée, l’utilisateur peut recevoir le fichier en tant que téléchargement. À l’aide des paramètres de rapport et des paramètres de format, vous pouvez exporter le rapport dans un état spécifique, notamment les données filtrées, les tailles de page personnalisées et d’autres paramètres spécifiques au format. Comme l’API est asynchrone, il peut prendre un certain temps pour que le fichier soit disponible.
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 cadres.
Utilisation de l’API
Conditions requises pour la licence
- Le rapport que vous exportez doit résider dans un espace de travail soutenu par une capacité Premium, Incorporée ou Fabric.
exportToFileL’API offre une prise en charge limitée dans Premium par utilisateur (PPU).
Événements de rendu
Pour vous assurer que l’exportation ne commence pas avant la fin du rendu du visuel, utilisez l’API d’événements « Rendu » et commencez uniquement l’exportation lorsque le rendu est terminé.
Sondages
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 API d’interrogation renvoie 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 différents 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. La première consiste à exporter les quatre premières pages d’un rapport à l’aide de la taille de page de rapport vers un fichier .pptx. Le deuxième exemple consiste à exporter la troisième page d’un rapport vers un fichier .jpeg.
Exportation des quatre premières pages vers un .pptx
{
"format": "PPTX",
"paginatedReportConfiguration":{
"formatSettings":{
"UseReportPageSize": "true",
"StartPage": "1",
"EndPage": "4"
}
}
}
Exportation de la troisième page vers un .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 ensemble de paramètres de rapport. Cette opération s'effectue à l'aide des capacités du paramètre de rapport .
Voici un exemple pour définir des 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 à l’aide d’un utilisateur (ou d’un utilisateur maître) ou d’un principal de service .
Sécurité au niveau des lignes (SNL)
Lorsque vous utilisez un modèle sémantique Power BI qui a la sécurité au niveau des lignes (RLS) définie comme source de données, vous pouvez exporter un rapport affichant des données visibles uniquement pour certains utilisateurs. Par exemple, si vous exportez un rapport de ventes défini avec des rôles régionaux, vous pouvez filtrer le rapport par programmation afin qu’une seule région soit affichée.
Pour exporter à l’aide de RLS, vous devez disposer d’une autorisation de lecture pour le modèle sémantique Power BI que le rapport utilise comme source de données.
Voici un exemple de fourniture d’un nom d’utilisateur effectif pour RLS.
{
"format": "PDF",
"paginatedReportConfiguration":{
"identities": [
{"username": "john@contoso.com"}
]
}
}
Authentification unique (SSO) pour SQL et Dataverse
Dans Power BI, vous avez la possibilité de définir OAuth avec l’authentification unique. Lorsque vous le faites, les informations d’identification de l’utilisateur qui consultent le rapport sont utilisées pour récupérer des données. Le jeton d’accès dans l’en-tête de requête n’est pas utilisé pour accéder aux données. Le jeton doit être transmis avec l’identité effective dans le corps du message.
L’obtention du jeton d’accès correct pour la ressource que vous souhaitez accéder peut parfois être difficile.
- 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 des jetons à 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
Le 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 de dépasser la limite et d’obtenir une erreur Trop de requêtes (429), distribuez la charge au fil du temps ou entre 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 la fenêtre de cinq minutes entraînent une erreur Trop de requêtes (429).
Exemples de code
Le Kit de développement logiciel (SDK) de l’API Power BI utilisé dans les exemples de code peut être téléchargé ici.
Lorsque vous créez un travail d’exportation, il existe trois étapes à suivre :
- Envoi d’une demande d’exportation.
- Sondages.
- 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 d’exportation. Dans cet exemple, une demande d’exportation est envoyée pour une plage de pages, une taille et des valeurs de paramètres 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
Une fois que vous avez envoyé une demande d’exportation, utilisez l’interrogation pour identifier le moment où le fichier d’exportation 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 a retourné une URL, vous pouvez utiliser cet exemple pour récupérer le 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. Cet exemple inclut 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é qui a un modèle sémantique Power BI comme source de données 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 utilise DirectQuery vers Azure Analysis Services ou un autre modèle sémantique Power BI, et une identité effective a été fournie.
L’exportation d’un rapport paginé avec une source de données Azure Analysis Services 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 tenant.
L’exportation d’un rapport est limitée à 60 minutes, qui correspond à la durée de vie du jeton d’accès utilisateur. Si vous recevez une erreur de délai d’expiration au-delà de la marque de 60 minutes lors de l’exportation de grandes quantités de données, envisagez de réduire la quantité de données à l’aide de 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
Passez en revue comment incorporer du contenu pour vos clients et votre organisation :