Dossier de rapport de projet Power BI Desktop

Important

Les projets Power BI Desktop sont actuellement en préversion.

Cet article décrit les fichiers et sous-dossiers dans le dossier Report d’un projet Microsoft Power BI Desktop. Les fichiers et sous-dossiers représentent ici un rapport Power BI. Selon votre projet, le dossier de rapport peut inclure :

• .pbi\
  • localSettings.json
• CustomVisuals\
• StaticResources\
  • RegisteredResources\
• semanticModelDiagramLayout.json
• definition.pbir¹
• mobileState.json
• report.json²
• Dossier definition\³
• .platform

1 – Ce fichier est nécessaire.
2 : ce fichier est requis lors de l’enregistrement au format PBIR-Legacy.
3 : ce fichier est requis lors de l’enregistrement au format PBIR.

Tous les dossiers de rapport de projet ne comprennent pas tous les fichiers et sous-dossiers décrits ici.

Fichiers de rapports

.pbi\localSettings.json

Contient des paramètres de rapport qui s’appliquent uniquement à l’utilisateur actuel et à l’ordinateur local. Il doit être inclus dans gitIgnore ou d’autres exclusions de contrôle de code source. Par défaut, Git ignore ce fichier.

Pour plus d’informations, consultez le document de schéma localSettings.json.

CustomVisuals\

Sous-dossier qui contient des métadonnées pour les visuels personnalisés dans le rapport. Power BI prend en charge trois types de visuels personnalisés :

• Visuels du magasin d’organisation : les organisations peuvent approuver et déployer des visuels personnalisés sur Power BI pour leur organisation. Pour plus d’informations, consultez Magasin d’organisation.
• Visuels Power BI AppSource : également appelés « visuels personnalisés publics ». Ces visuels sont disponibles à partir de Microsoft AppSource. Les développeurs de rapports peuvent installer ces visuels directement à partir de Power BI Desktop.
• Fichiers visuels personnalisés : également appelés « visuels personnalisés privés ». Les fichiers peuvent être chargés dans le rapport en chargeant un package pbiviz.

Seuls les visuels personnalisés privés sont chargés dans le dossier CustomVisuals. Les visuels AppSource et Organization sont chargés automatiquement par Power BI Desktop.

RegisteredResources\

Sous-dossier qui inclut des fichiers de ressources spécifiques au rapport et chargés par l’utilisateur, tels que des thèmes, des images et des visuels personnalisés (fichiers pbiviz).

Les développeurs sont responsables des fichiers ici et les modifications sont prises en charge. Par exemple, vous pouvez modifier un fichier et après le redémarrage d’un Power BI Desktop, le nouveau fichier est chargé dans le rapport. Ce dossier peut débloquer certains scénarios utiles, tels que :

• Création de thèmes personnalisés en dehors de Power BI Desktop à l’aide du schéma public.
• Application de modifications par lot en modifiant le fichier de ressources sur plusieurs rapports. Par exemple, vous pouvez basculer le thème personnalisé d’entreprise, changer entre les thèmes clairs et sombres, et modifier les images de logo.

Chaque fichier de ressources doit avoir une entrée correspondante dans le fichier report.json, qui pendant la préversion ne prend pas en charge la modification. Les modifications des fichiers RegisteredResources sont uniquement prises en charge pour les ressources déjà chargées qui entraînent l’inscription de la ressource par Power BI Desktop dans report.json.

semanticModelDiagramLayout.json

Contient des diagrammes de modèle de données décrivant la structure du modèle sémantique associé au rapport. Pendant la préversion, ce fichier ne prend pas en charge la modification externe.

definition.pbir

Contient la définition globale d’un rapport et des paramètres principaux. Ce fichier contient également la référence au modèle sémantique utilisé par le rapport. Power BI Desktop peut ouvrir un fichier pbir directement, comme si le rapport était ouvert à partir d’un fichier pbip. L’ouverture d’un fichier pbir ouvre également le modèle sémantique à côté s’il existe une référence relative utilisant byPath.

Exemple de fichier definition.pbir :

{
  "version": "1.0",
  "datasetReference": {
    "byPath": {
      "path": "../Sales.Dataset"
    },
    "byConnection": null
  }
}

La définition inclut la propriété datasetReference qui fait référence au modèle sémantique utilisé dans le rapport. La référence peut être :

byPath – Spécifie un chemin d’accès relatif au dossier du modèle sémantique cible. Les chemins d’accès absolus ne sont pas pris en charge. Une barre oblique (/) est utilisée comme séparateur de dossiers. Lorsqu’elle est utilisée, Power BI Desktop ouvre également le modèle sémantique en mode édition complète.

byConnection – Spécifie un modèle sémantique distant dans le service Power BI en utilisant une chaîne de connexion. Lorsqu’une référence byConnection est utilisée, Power BI Desktop n’ouvre pas le modèle sémantique en mode édition.

En utilisant la référence byConnection, les propriétés suivantes doivent être spécifiées :

Propriété	Description
connectionString	Chaîne de connexion faisant référence au modèle sémantique distant.
pbiModelDatabaseName	ID du modèle sémantique distant.
connectionType	Type de connexion. Pour le modèle sémantique distant de service, cette valeur doit être pbiServiceXmlaStyleLive.
pbiModelVirtualServerName	Propriété interne qui doit avoir la valeur sobe_wowvirtualserver.

Exemple utilisant byConnection :

{
  "version": "1.0",
  "datasetReference": {
    "byPath": null,
    "byConnection": {
      "connectionString": "Data Source=powerbi://api.powerbi.com/v1.0/myorg/WorkpaceName;Initial Catalog=SemanticModelName;Integrated Security=ClaimsToken",
      "pbiServiceModelId": null,
      "pbiModelVirtualServerName": "sobe_wowvirtualserver",
      "pbiModelDatabaseName": "e244efd3-e253-4390-be28-6be45d9da47e",
      "connectionType": "pbiServiceXmlaStyleLive",
      "name": null
    }
  }
}

Quand le modèle sémantique et le rapport partagent le même espace de travail, Intégration de Fabric Git utilise toujours une référence byPath au modèle sémantique.

Ce fichier spécifie également les formats de définition de rapport pris en charge par le biais de la propriété « version ».

Version	Formats pris en charge
1.0	La définition de rapport doit être stockée en tant que fichier PBIR-Legacy dans le fichier report.json.
4.0 ou version ultérieure	La définition de rapport peut être stockée en tant que fichier PBIR-Legacy (report.json) ou PBIR (dossier \definition).

Pour plus d’informations, consultez le document de schéma de definition.pbir.

mobileState.json

Contient les paramètres d’apparence et de comportement du rapport lors du rendu sur un appareil mobile. Ce fichier ne prend pas en charge la modification externe.

report.json

Ce fichier contient la définition de rapport au format Rapport Power BI hérité (PBIR-Legacy) et ne prend pas en charge la modification externe.

Dossier definition\

Ce dossier est disponible uniquement si le projet Power BI est enregistré à l’aide du format Rapport amélioré Power BI (PBIR). Il remplace le fichier report.json.

Mail Luck!.

Le fichier de plateforme Fabric qui contient les propriétés vitales pour établir et maintenir la connexion entre des éléments Fabric et Git.

Pour plus d’informations, consultez Fichiers systèmes de l’intégration Git générés automatiquement.

Format PBIR

Important

Tenez compte de toutes les limitations PBIR pendant la phase de préversion.

L’enregistrement de vos fichiers Projet Power BI (PBIP) à l’aide du format Rapport amélioré Power BI (PBIR) améliore considérablement le suivi des modifications et la résolution des conflits de fusion à l’aide de fichiers JSON correctement mis en forme.

Chaque page, visuel, signet, etc., est organisé en un fichier individuel distinct au sein d’une structure de dossiers. Ce format est idéal pour la résolution des conflits de co-développement.

Contrairement à PBIR-Legacy (report.json), PBIR est un format documenté publiquement qui prend en charge les modifications provenant d’applications autres que Power BI. Chaque fichier a un schéma JSON public, qui documente non seulement le fichier, mais qui permet également aux éditeurs de code tels que Visual Studio Code d’effectuer la validation de la syntaxe lors de la modification.

Voici quelques-uns des scénarios possibles disponibles avec PBIR :

• Copier des pages/visuels/signets entre des rapports.
• Vérifier la cohérence d’un ensemble de visuels sur toutes les pages, en copiant et collant les fichiers visuels.
• Rechercher et remplacer facilement plusieurs fichiers de rapports.
• Appliquer une modification par lots sur tous les visuels à l’aide d’un script (par exemple, masquez les filtres au niveau du visuel)

Activer la fonctionnalité d’évaluation du format PBIR

L’enregistrement en tant que Power BI à l’aide de PBIR est actuellement en préversion. Avant d’utiliser cette fonctionnalité, activez-la dans les fonctionnalités en préversion de Power BI Desktop :

Accédez à Fichier > Options et paramètres > Options > Fonctionnalités en préversion, et cochez la case en regard de Enregistrer les rapports avec le format de métadonnées amélioré (PBIR).

Enregistrer en tant que projet au format PBIR

Une fois la fonctionnalité en préversion PBIR activée, lorsque vous enregistrez un projet, votre rapport est enregistré dans un dossier nommé \definition à l’intérieur du dossier de rapport :

En savoir plus sur la structure du dossier PBIR.

Convertir un fichier PBIP existant en PBIR

Si vous disposez déjà d’un PBIP utilisant le format PBIR-Legacy, vous pouvez le convertir en PBIR de la manière suivante :

1. Ouvrez le fichier PBIP dans Power BI Desktop.

2. Assurez-vous de l’activation de la fonctionnalité d’évaluation.

3. Enregistrez le projet. Une invite s’affiche vous demandant de procéder à une mise à niveau vers PBIR.

4. Sélectionnez Mettre à niveau.

   

   Important

   Une fois que vous effectuez la mise à niveau vers PBIR, vous ne pouvez pas revenir à PBIR-Legacy. Si vous envisagez un éventuel retour à PBIR-Legacy, enregistrez une copie de vos fichiers PBIP au préalable.

Le fichier PBIR-Legacy existant (report.json) est remplacé par un dossier \definition contenant la représentation PBIR du rapport.

Si vous sélectionnez Conserver le format actuel, l’appareil de bureau ne vous invitera plus à effectuer la mise à niveau.

Publier un rapport PBIR sur service

Dans la phase de préversion, la seule façon de publier un rapport avec le format PBIR est l’intégration de Fabric Git. Cela implique de connecter l’espace de travail à un référentiel Git et d’envoyer (push) le rapport PBIR vers celui-ci, qui peut ensuite être synchronisé avec l’espace de travail de service à un stade ultérieur.

Si vous souhaitez convertir un rapport existant en PBIR dans le service, procédez de la manière suivante :

1. Connectez votre espace de travail à Git.
2. Clonez le référentiel Git sur votre système de fichiers local.
3. Ouvrez le rapport dans Power BI Desktop en ouvrant le fichier definition.pbir.
4. Enregistrez le rapport et choisissez de procéder à une mise à niveau vers PBIR.
5. Validez et synchronisez les modifications apportées à Git.
6. Mettez à jour l’espace de travail en fonction des dernières modifications de Git.

Dossier et fichiers PBIR

La définition de rapport est stockée dans le dossier definition\ avec la structure suivante :

├── bookmarks\
│   ├── [bookmarkName].bookmark.json
|   └── bookmarks.json
├── pages\
│   ├── [pageName]\
│   |   ├── \visuals
|   │   |   ├── [visualName]\
|   |   │   │   |── mobile.json
|   |   |   └   └── visual.json
|   |   └── page.json
|   └── pages.json
├── version.json
├── reportExtensions.json
└── report.json

Fichier/Dossier	Requis	Description
bookmarks\	Non	Dossier contenant tous les fichiers de signet du rapport.
── [bookmarkName].bookmark.json	Non	Métadonnées de signet, telles que les visuels cibles et les filtres. Pour plus d’informations, consultez le schéma.
── bookmarks.json	Non	Métadonnées de signets, telles que l’ordre et les groupes de signets. Pour plus d’informations, consultez le schéma.
pages\	Oui	Dossier contenant toutes les pages du rapport.
── [pageName]\	Oui	Un dossier par page.
──── visuals\	Non	Dossier contenant tous les visuels de la page.
────── [visualName]\	Non	Un dossier par visuel.
──────── mobile.json	Non	Métadonnées de disposition mobile visuelles, telles que la position mobile et la mise en forme. Pour plus d’informations, consultez le schéma.
──────── visual.json	Oui	Métadonnées visuelles, telles que la position et la mise en forme, la requête. Pour plus d’informations, consultez le schéma.
──── page.json	Oui	Métadonnées de page, telles que les filtres au niveau de la page et la mise en forme. Pour plus d’informations, consultez le schéma.
── pages.json	Non	Métadonnées de pages, telles que l’ordre des pages et la page active. Pour plus d’informations, consultez le schéma.
version.json	Oui	La version du fichier PBIR, entre autres facteurs, détermine les fichiers qui doivent être chargés. Pour plus d’informations, consultez le schéma
reportExtensions.json	Non	Extensions de rapport, telles que les mesures au niveau du rapport. Pour plus d’informations, consultez le schéma
report.json	Oui	Métadonnées de rapport, telles que les filtres au niveau du rapport et la mise en forme. Pour plus d’informations, consultez le schéma

Convention d’affectation de noms PBIR

Tous les noms à l’intérieur des crochets ([]) dans le tableau précédent suivent une convention d’affectation de noms par défaut, mais peuvent être renommés en noms plus conviviaux. Par défaut, les pages, les visuels et les signets utilisent leur nom d’objet de rapport comme nom de fichier ou de dossier. Ces noms d’objets sont initialement un identificateur unique de 20 caractères, tel que « 90c2e07d8e84e7d5c026 ».

Le renommage de la propriété « name » dans chaque fichier JSON est pris en charge, mais peut interrompre les références externes à l’intérieur et à l’extérieur du rapport. Le nom de l’objet et/ou le nom du fichier/dossier doit se composer d’un ou plusieurs caractères de mot (lettres, chiffres, traits de soulignement) ou de traits d’union.

Après avoir renommé des fichiers ou dossiers PBIR, vous devez redémarrer Power BI Desktop. Au redémarrage, Power BI Desktop conserve les noms de fichiers ou de dossiers d’origine lors de l’enregistrement.

Schémas JSON PBIR

Chaque fichier JSON PBIR inclut une déclaration schéma JSON en haut du document. Ce schéma d’URL est accessible publiquement et peut être utilisée pour en savoir plus sur les propriétés et objets disponibles de chaque fichier. En outre, il fournit un IntelliSense et une validation intégrés lors de la modification avec des éditeurs de code tels que Visual Studio Code.

Le schéma d’URL définit également la version du document, qui est censée changer à mesure que la définition du rapport évolue.

Tous les schémas JSON sont publiés ici.

Annotations PBIR

Vous pouvez inclure des annotations en tant que paires nom-valeur dans la définition de rapport pour chaque visualet page report. Bien que Power BI Desktop ignore ces annotations, elles peuvent être utiles pour les applications externes telles que les scripts.

Par exemple, vous pouvez spécifier la page par défaut du rapport au niveau du report.json fichier, qui peut ensuite être utilisée par un script de déploiement.

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/report/1.0.0/schema.json",
  "themeCollection": {
    "baseTheme": {
      "name": "CY24SU06",
      "reportVersionAtImport": "5.55",
      "type": "SharedResources"
    }
  },
  ...
  "annotations": [
    {
      "name": "defaultPage",
      "value": "c2d9b4b1487b2eb30e98"
    }
  ]
}

Modifications externes apportées aux fichiers PBIR

Vous pouvez modifier les fichiers JSON PBIR à l’aide d’un éditeur de code comme Visual Studio Code ou d’un outil externe, tant que le fichier respecte le schéma JSON. L’utilisation d’un nom ou d’un type de propriété incorrect peut être facilement détectée directement dans Visual Studio Code :

Les modifications externes apportées au contenu PBIR peuvent entraîner des erreurs lors de la réouverture des fichiers dans Power BI Desktop. Ces erreurs peuvent être de deux types :

Les erreurs bloquantes empêchent Power BI Desktop d’ouvrir le rapport. Ces erreurs permettent d’identifier le problème et le fichier incriminé qui doit être résolu avant d’être ouvert à nouveau :

Les erreurs telles qu’un schéma non valide ou l’absence de propriétés requises sont considérées comme des erreurs bloquantes. Ces erreurs peuvent être facilement identifiées en ouvrant le fichier dans Visual Studio Code et en inspectant les erreurs de schéma.

Les erreurs non bloquantes n’empêchent pas Power BI Desktop d’ouvrir le rapport et sont automatiquement résolues.

Les erreurs telles qu’une configuration activePageName non valide sont des exemples d’erreurs non bloquantes qui sont automatiquement corrigées. L’avertissement est nécessaire pour vous donner la possibilité d’éviter d’enregistrer le rapport avec la correction automatique, en empêchant toute perte potentielle de travail.

Erreurs PBIR courantes

Scénario : après avoir renommé des noms de dossiers visuels ou de pages, mon visuel ou page ne s’affiche plus lors de l’ouverture du rapport.

Solution : Vérifiez si le nom est conforme à la convention d’affectation de noms. Si ce n’est pas le cas, Power BI Desktop ignore le fichier ou le dossier et le traite comme des fichiers d’utilisateur privés.

Scénario : les nouveaux objets de rapport sont nommés différemment des autres. Par exemple, la plupart des dossiers de page sont nommés « ReportSection0e71dafbc949c0853608 », tandis que quelques-uns sont nommés « 1b3c2ab12b603618070b ».

Solution: PBIR a adopté une nouvelle convention d’affectation de noms pour chaque objet, mais elle s’applique uniquement aux nouveaux objets. Lorsque vous enregistrez un rapport existant en tant que PBIP, les noms actuels doivent être conservés pour empêcher les références cassantes. Pour garder une cohérence, un script de renommage par lot est autorisé.

Scénario : j’ai copié un fichier de signets et, lors de l’enregistrement, la plupart de la configuration de signet a été supprimée.

Solution : Ce comportement est intentionnel, les signets de rapport capturent l’état d’une page de rapport ainsi que tous ses visuels. Étant donné que l’état capturé provient d’une autre page de rapport avec différents visuels, tous les visuels non valides sont supprimés de la configuration du signet. Si vous copiez également les visuels et la page qui en dépendent, le signet conserve sa configuration.

Scénario : j’ai copié un dossier de page à partir d’un autre rapport et rencontré une erreur indiquant que « Les valeurs de la propriété « pageBinding.name » doivent être uniques.

Solution : L’objet pageBinding est nécessaire pour prendre en charge les info-bulles d’extraction et de page. Puisqu’ils peuvent être référencés par d’autres pages, le nom doit être unique dans le rapport. Dans la page nouvellement copiée, affectez une valeur unique pour résoudre l’erreur. Après juin 2024, cette situation n’est plus un problème, car le nom de pageBinding est un GUID par défaut.

Considérations et limitations de fichier PBIR

PBIR est actuellement en préversion. N’oubliez pas les éléments suivants :

• Limitations de service
  • Les affichages mobiles ne sont pas affichés dans Power BI Apps.
  • Impossible de le déployer avec des pipelines de déploiement.
  • Impossible de l’enregistrer en tant que copie.
• Les rapports volumineux de plus de 500 fichiers rencontrent des problèmes de performances de création (l’affichage des rapports n’est pas affecté), notamment :
  • L’enregistrement dans Power BI Desktop
  • La synchronisation dans l’intégration Fabric Git
• Une fois qu’un rapport PBIR-Legacy est converti en PBIR, il est impossible de le restaurer.
• La conversion d’un fichier PBIP en fichier PBIX à l’aide de la fonctionnalité « Enregistrer sous » incorpore le rapport PBIR dans le fichier PBIX, apportant toutes les limitations PBIR au fichier PBIX.

Limitations de taille de PBIR appliquées par le service :

• 1 000 pages maximales par rapport.
• 300 visuels max par page.
• 5 Mo maximum pour chaque fichier de signets.
• 1 Mo maximum pour chaque fichier.
• 1 000 fichiers de package de ressources max par rapport.
• Taille maximale de 300 Mo pour tous les fichiers de package de ressources.
• Taille maximale de 20 Mo de tous les fichiers de rapport.

Pendant la préversion publique, les API REST Fabric et Intégration Fabric Git continuent d’utiliser PBIR-Legacy (report.json) lors de l’exportation des définitions de rapport. Toutefois, si le rapport est importé dans Fabric en utilisant le format PBIR, les deux fonctionnalités commencent à exporter la définition de rapport en tirant parti du format PBIR.

Contenu connexe

• Dossier des modèles sémantiques des projets Power BI Desktop
• Projets Power BI Desktop