Tableau de bord en temps réel - Intégration Git

Cet article détaille la structure des dossiers et des fichiers pour Real-Time éléments de tableau de bord une fois qu’ils sont synchronisés avec un dépôt GitHub ou Azure Devops.

Structure de dossiers

Une fois qu’un espace de travail est synchronisé avec un dépôt, vous voyez un dossier de niveau supérieur pour l’espace de travail et un sous-dossier pour chaque élément synchronisé. Chaque sous-dossier est mis en forme avec le nom de l’élément. Type d’élément

Dans le dossier du tableau de bord, vous voyez les fichiers suivants :

Plateforme : définit des valeurs de plateforme de structure telles que le nom d’affichage et la description.
Propriétés : définit des valeurs spécifiques à l’élément.

Voici un exemple de structure de dossiers :

dépôt

Espace de travail A
- Item_A.KQLDashboard
  - .plateforme
  - RealTimeDashboard-1.json
Espace de travail B
- Item_B.KQLDashboard
  - .plateforme
  - RealTimeDashboard-2.json

fichiers de tableau de bord Real-Time

Les fichiers suivants sont contenus dans un dossier de tableau de bord :

.plateforme

Le fichier utilise le schéma suivant pour définir un tableau de bord en temps réel :

{
  "$schema": "https://developer.microsoft.com/json-schemas/fabric/gitIntegration/platformProperties/2.0.0/schema.json",
  "metadata": {
    "type": "KQLDashboard",
    "displayName": "",
    "description": ""
  },
  "config": {
    "version": "2.0",
    "logicalId": ""
  }
}

RealTimeDashboard.json

Le fichier utilise le schéma suivant pour définir un tableau de bord en temps réel :

{
  "$schema": "",
  "id": "",
  "eTag": "\"\"",
  "schema_version": "",
  "title": "",
  "tiles": [
    {
      "id": "",
      "title": "",
      "visualType": "",
      "pageId": "",
      "layout": {
        "x": ,
        "y": ,
        "width": ,
        "height":
      },
      "queryRef": {
        "kind": "",
        "queryId": ""
      },
      "visualOptions": {
        "multipleYAxes": {
          "base": {
            "id": "",
            "label": "",
            "columns": [],
            "yAxisMaximumValue": ,
            "yAxisMinimumValue": ,
            "yAxisScale": "",
            "horizontalLines": []
          },
          "additional": [],
          "showMultiplePanels":
        },
        "hideLegend": ,
        "legendLocation": "",
        "xColumnTitle": "",
        "xColumn": ,
        "yColumns": ,
        "seriesColumns": ,
        "xAxisScale": "",
        "verticalLine": "",
        "crossFilterDisabled": ,
        "drillthroughDisabled": ,
        "crossFilter": [
          {
            "interaction": "",
            "property": "",
            "parameterId": "",
            "disabled":
          }
        ],
        "drillthrough": [],
        "selectedDataOnLoad": {
          "all": ,
          "limit":
        },
        "dataPointsTooltip": {
          "all": ,
          "limit":
        }
      }
    }
  ],
  "baseQueries": [],
  "parameters": [
    {
      "kind": "",
      "id": "",
      "displayName": "",
      "description": "",
      "variableName": "",
      "selectionType": "",
      "includeAllOption": ,
      "defaultValue": {
        "kind": ""
      },
      "dataSource": {
        "kind": "",
        "columns": {
          "value": ""
        },
        "queryRef": {
          "kind": "",
          "queryId": ""
        }
      },
      "showOnPages": {
        "kind": ""
      },
      "allIsNull":
    },
  ],
  "dataSources": [
    {
      "id": "",
      "name": "",
      "clusterUri": "",
      "database": "",
      "kind": "",
      "scopeId": ""
    }
  ],
  "pages": [
    {
      "name": "",
      "id": ""
    }
  ],
  "queries": [
    {
      "dataSource": {
        "kind": "",
        "dataSourceId": ""
      },
      "text": "",
      "id": "",
      "usedVariables": [
        "",
        ""
      ]
    }
  ]
}

Validation du tableau de bord en temps réel

Le point de terminaison de chargement du tableau de bord Real-Time valide le JSON au-delà de la conformité du schéma standard. Les violations s’affichent pour les utilisateurs dans l’interface utilisateur du tableau de bord en tant que messages d’erreur tels que : Error loading dashboard / Error found at: /<section> / Message: <reason>.

Unicité des références de requête

Tous les queryId tableaux de bord doivent être référencés exactement une fois, comptabilisés entre :

tiles[].queryRef.queryId
baseQueries[].queryId
parameters[].dataSource.queryRef.queryId

Si une queryId vignette est partagée entre deux vignettes ou entre une vignette et une baseQuery, la validation échoue avec : /queries: Some query IDs are used in multiple query references (tiles, base queries, parameters).

Lors de la duplication d’une vignette vers une nouvelle page par programmation, dupliquez également la requête (affectez un nouveau queryId, conservez la même text et dataSource) et pointez les nouvelles vignettes queryRef.queryId sur la nouvelle requête.

Unicité et format de l’ID

Chaque id dans tiles[], queries[], baseQueries[], parameters[], dataSources[], et pages[] doit être :

Unique dans sa catégorie.
RFC 4122 UUID valide (par exemple). 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a Les chaînes lisibles qui ont des tirets (par exemple, my-tile-0001-0000-0000-000000000001) sont rejetées au moment du chargement avec : Needs to follow the UUID format as defined by RFC 4122.

Pour les modifications par programmation, générez des ID avec une bibliothèque UUID : uuid.uuid4() pour les ID frais ou uuid.uuid5(namespace, label) pour les ID déterministes qui survivent aux réexécutions de script.

Conseil / Astuce

Si vous voyez une erreur de chargement comme /tiles/N/queryRef ... must have required property 'baseQueryId', l’erreur réelle est généralement un élément malformé queryRef.queryId, pas un élément manquant baseQueryId. Le schéma queryRef est un oneOf entre { kind: "query", queryId: <uuid> } et { kind: "baseQuery", baseQueryId: <uuid> }. Lorsque l’UUID interne n’est pas valide, le validateur échoue la branche query-kind et signale à la place les échecs provenant de la branche baseQuery-kind. Corrigez l’UUID et l’effacement en cascade.

Conservation des identités entre les modifications

Pour conserver le lien entre le fichier et l’élément d’espace de travail en direct, ne modifiez pas les éléments suivants sur les entrées existantes :

Niveau supérieur : id, eTag, schema_version
Par vignette : id, pageId, queryRef.queryId
Par requête : id, dataSource.dataSourceId
Par source de données : id, scopeId
Par page : id
Par paramètre : id, variableName (et beginVariableName / endVariableName pour kind: "duration")
.platform: config.logicalId

La modification de ces identificateurs entraînera le traitement de la modification comme une suppression et une recréation lors de la prochaine Update from Git, ce qui entraînera une perte de contexte : références d'éléments épinglés, objets de partage et tout état attaché à l’original id.

Parameters

Lorsqu’une vignette qui utilise un paramètre (référencé par le biais de usedVariablesla requête) est ajoutée à une nouvelle page, ce paramètre n’apparaît pas automatiquement sur la nouvelle page. Si le paramètre showOnPages.kind est "selection", vous devez ajouter la nouvelle page id à showOnPages.pageIds. Si le paramètre est utilisable defaultValue, la vignette s’affiche avec la valeur par défaut.

Les paramètres à plusieurs variables, tels que kind: "duration" les paramètres, exposent deux variables via beginVariableName et endVariableName (couramment _startTime et _endTime). Ils partagent un seul objet de paramètre avec un showOnPages réglage.

Exemples de modifications via Git

L’utilisation des notes de schéma et de validation vous permet d’apporter des modifications au tableau de bord Real-Time via Git au lieu de l’interface utilisateur.

Exemple : Copier une vignette dans une nouvelle page

Pour copier une vignette de la page A vers une page B nouvellement ajoutée en modifiant RealTimeDashboard-N.json:

Ajouter la page B à pages[] avec un nouveau id.
Effectuez une copie en profondeur de la vignette source dans tiles[]. Assigner:
- nouvelle vignette id (nouveau GUID)
- pageId = ID de la page B
Recherchez la requête source dans queries[] par la vignette queryRef.queryId source.
Effectuez une copie en profondeur de la requête dans queries[] avec un nouveau id.
Effectuez la mise à jour du queryRef.queryId de la tuile clonée pour celle de la nouvelle requête id.
Pour chaque paramètre référencé dans la requête usedVariables[]cloné : si showOnPages.kind == "selection", ajoutez l’ID de la page B à showOnPages.pageIds.
Vérifiez qu’aucun queryId n’apparaît plus d’une fois dans tiles[], baseQueries[] et parameters[].dataSource.queryRef.
Validez, envoyez et exécutez Update à partir de Git sur l’espace de travail.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-04-28