Dossier de rapport de projet Power BI Desktop

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\³
• .plateforme

1 – Ce fichier est nécessaire.
2 - Ce fichier est requis pour PBIR-Legacy format.
3 - Ce fichier est requis pour le 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. 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. 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 a été ouvert à partir d’un fichier PBIP. L’ouverture d’un fichier PBIR ouvre également le modèle sémantique si une référence relative utilise byPath.

Exemple de fichier definition.pbir :

{  
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byPath": {
      "path": "../Sales.Dataset"
    }    
  }
}

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 la connexion à un modèle sémantique dans un espace de travail Fabric à l’aide d’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.

Version 2

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

Propriété	Descriptif
chaîne de connexion	Chaîne de connexion faisant référence au modèle sémantique dans un espace de travail Fabric.

Exemple utilisant byConnection :

{  
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byConnection": {      
      "connectionString": "Data Source=\"powerbi://api.powerbi.com/v1.0/myorg/[WorkpaceName]\";initial catalog=[SemanticModelName];access mode=readonly;integrated security=ClaimsToken;semanticmodelid=[SemanticModelId]"
    }
  }
}

Lors du déploiement d’un rapport via l’API REST Fabric, vous devez uniquement spécifier la semanticmodelid propriété. Par exemple:

{  
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/2.0.0/schema.json",
  "version": "4.0",
  "datasetReference": {
    "byConnection": {      
      "connectionString": "semanticmodelid=[SemanticModelId]"
    }
  }
}

Version 1

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

Propriété	Descriptif
chaîne de connexion	Chaîne de connexion faisant référence au modèle sémantique dans un espace de travail Fabric.
pbiModelDatabaseName	ID du modèle sémantique distant.
type de connexion	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.
pbiServiceModelId	Propriété interne qui doit avoir la valeur null.
nom	Propriété interne qui doit avoir la valeur EntityDataSource.

Exemple utilisant byConnection :

{
    "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definitionProperties/1.0.0/schema.json",
    "version": "4.0",
    "datasetReference": {  
      "byConnection": {
        "connectionString": "Data Source=powerbi://api.powerbi.com/v1.0/myorg/[WorkpaceName];Initial Catalog=[SemanticModelName];Integrated Security=ClaimsToken",
        "pbiServiceModelId": null,
        "pbiModelVirtualServerName": "sobe_wowvirtualserver",
        "pbiModelDatabaseName": "[Semantic Model Id]",
        "connectionType": "pbiServiceXmlaStyleLive",
        "name": "EntityDataSource"
      }
  }
}

Important

Lors du déploiement d’un rapport via l’API REST Fabric, vous devez utiliser byConnection références. Cela ne doit pas être confondu avec le mode de stockage d’un modèle sémantique tel que DirectQuery. Le datasetReference rapport spécifie uniquement le modèle sémantique auquel le rapport se connecte, mais ne définit pas la façon dont ce modèle stocke ou accède à ses données.

Plusieurs fichiers *.pbir

Lorsque le modèle sémantique et le rapport partagent le même espace de travail, l’intégration Git Fabric exporte toujours des définitions avec une byPath référence au modèle sémantique. Si vous souhaitez forcer l'ouverture du rapport en connexion directe (par exemple, pour utiliser des mesures au niveau du rapport), vous pouvez avoir plusieurs fichiers *.pbir, comme un fichier avec une connexion byPath et un autre avec une connexion byConnection. Fabric Git Integration traite uniquement le fichier definition.pbir et ignore tous les autres fichiers *.pbir. Toutefois, ces fichiers peuvent coexister dans le même référentiel.

  ├── definition\
  ├── StaticResources\
  ├── .platform
  ├── definition-liveConnect.pbir
  └── definition.pbir

Le definition.pbir 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, veuillez consulter le document de schéma 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.

.plateforme

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 les fichiers système générés automatiquement de l’intégration Git.

Format PBIR

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 codé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)

Enregistrer en tant que projet au format PBIR

Lorsque vous enregistrez un projet à l’aide de PBIR, 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.

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	Descriptif
Signets\	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.
<>>>> visuels\	Non	Dossier contenant tous les visuels de la page.
────── [visualName]\	Non	Un dossier par visuel.
──────── mobile.json	Non	Métadonnées de mise en page mobile visuelles, telles que la position sur 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

Important

Certains fichiers de métadonnées de rapport, tels que visual.json ou bookmarks.json, peuvent être enregistrés avec des valeurs de données à partir de votre modèle sémantique. Par exemple, si vous appliquez un filtre à un visuel pour le champ « Société » = « Contoso », la valeur « Contoso » est conservée dans le cadre des métadonnées. Ceci s’applique également à d’autres configurations telles que les sélections de segment, la largeur des colonnes personnalisées de la matrice et la mise en forme pour des séries spécifiques.

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 risque d’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.

Copier le nom de l’objet de rapport

Chaque objet du rapport est enregistré dans un dossier ou un fichier distinct, mais le nom du dossier n’est pas toujours évident. Pour faciliter cette opération, vous pouvez copier le nom de n’importe quel nom d’objet de rapport (y compris les pages, les visuels, les signets et les filtres) directement à partir de Power BI dans votre Presse-papiers.

À partir du bureau

1. Accédez à Fichier > Options et paramètres > Paramètres du rapport > Objets du rapport et activez le paramètre Copier les noms des objets lors d'un clic droit sur les objets du rapport. Cela doit être effectué une seule fois.

   

2. Cliquez avec le bouton droit sur n’importe quel objet de rapport et sélectionnez Copier le nom de l’objet.

   

Avec le nom de l’objet copié dans le Presse-papiers, vous pouvez facilement l’entrer dans la barre de recherche de l’Explorateur Windows ou de Visual Studio Code pour localiser ou identifier le nom de l’objet dans le dossier PBIR.

Depuis le service

1. Activez le paramètre permettant de copier les noms des objets lorsque vous cliquez avec le bouton droit sur les objets du rapport. Cela doit être effectué une seule fois. Vous n’avez pas besoin de l’activer pour chaque rapport.

   

2. Lors de la modification d’un rapport, cliquez avec le bouton droit sur n’importe quel objet de rapport et sélectionnez Copier le nom de l’objet.

   

Vous pouvez utiliser l’objet copié pour identifier les noms de fichiers au format de fichier PBIR ou pour résoudre les problèmes de performances via l’analyse de l’espace de travail ou Log Analytics pour lier la requête DAX à un visuel dans le rapport.

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 pagereport. 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 pris en charge dans un éditeur de code comme Visual Studio Code ou un autre outil externe pendant que le projet reste ouvert dans Power BI Desktop. Lorsque vous enregistrez les fichiers, Power BI Desktop détecte les modifications et affiche la bannière Appliquer les modifications externes. Sélectionnez Appliquer des modifications externes pour recharger la définition de rapport sans fermer et rouvrir le projet.

Avant de modifier des fichiers PBIR en externe, enregistrez les modifications apportées à Power BI Desktop. Si Power BI Desktop a des modifications non enregistrées lorsque vous appliquez les modifications externes, elle vous avertit que les modifications non enregistrées seront remplacées. Pour connaître les limitations et le flux de travail complets, consultez Modifier les fichiers PBIP en dehors de Power BI Desktop.

Les fichiers PBIR doivent être conformes à leurs schémas JSON. VS Code identifie les problèmes tels qu’un nom de propriété non pris en charge ou un type de propriété incorrect :

Les modifications externes apportées au contenu PBIR peuvent entraîner des erreurs lorsque vous appliquez les modifications ou ouvrez les fichiers dans Power BI Desktop. Ces erreurs peuvent être de deux types :

Les erreurs de blocage empêchent Power BI Desktop de charger les modifications du rapport. Ces erreurs identifient le problème et le fichier que vous devez corriger avant d’appliquer à nouveau les modifications :

Des erreurs telles qu’un schéma non valide ou des propriétés requises manquantes bloquent les erreurs. Pour identifier ces erreurs, ouvrez le fichier dans VS Code et inspectez les messages de validation de schéma.

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

Une configuration activePageName invalide est un exemple d’erreur non bloquante que Power BI Desktop corrige automatiquement. L’avertissement vous donne l’occasion de passer en revue la correction avant d’enregistrer le rapport et de remplacer la définition externe.

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 favoris et, lors de la sauvegarde, la plupart de la configuration des signets 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.

Convertir un rapport existant en PBIR

PBIR est généralement disponible et est le format de rapport par défaut. Vous pouvez toujours ouvrir des rapports qui utilisent PBIR-Legacy dans Power BI Desktop et le service Power BI. Lorsque vous modifiez et enregistrez un rapport PBIR-Legacy, Power BI en mode silencieux et le convertit automatiquement en PBIR.

Avant la conversion, Power BI crée une sauvegarde du rapport :

• Power BI Desktop conserve la sauvegarde pendant 30 jours dans l’un des emplacements suivants :
  • Version du Microsoft Store : %USERPROFILE%\Microsoft\Power BI Desktop Store App\TempSaves\Backups
  • Version du programme d’installation exécutable : %USERPROFILE%\AppData\Local\Microsoft\Power BI Desktop\TempSaves\Backups
• Le service Power BI conserve la sauvegarde PBIR-Legacy pendant 28 jours. Pour le restaurer, ouvrez les paramètres du rapport à partir de l’espace de travail, puis sélectionnez Restaurer en tant que PBIR-Legacy. Cette sauvegarde est créée uniquement pour les rapports convertis directement dans le service Power BI.

La restauration d’une sauvegarde PBIR-Legacy n’empêche pas une autre conversion. Pour conserver un rapport au format PBIR-Legacy, ne le modifiez pas dans le service Power BI ou utilisez une version de Power BI Desktop publiée avant septembre 2026.

Considérations et limitations de fichier PBIR

Gardez à l’esprit les considérations et limitations suivantes :

• Les filtres automatiques visuels sont conservés dans le fichier PBIR visual.json uniquement une fois que le volet de filtre a été développé au moins une fois lors de la modification du rapport.
• Si Power BI ne convertit pas un rapport PBIR-Legacy en PBIR lorsque vous modifiez et enregistrez-le, la conversion a rencontré un problème de produit. Créez une demande de support pour signaler le problème.

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

• 1 000 pages maximales par rapport.
• 1 000 visuels max par page.
• 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 300 Mo de tous les fichiers de rapport.

Important

Si vous atteignez les limites ci-dessus, vous devez envisager d’optimiser votre rapport. Consultez le document Optimisation de Power BI.

Intégration Git de Fabric et API REST de Fabric exportent des définitions de rapport à l’aide de PBIR.

Contenu connexe

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