Dashboard in tempo reale - Integrazione con Git

Questo articolo illustra in dettaglio la struttura di cartelle e file degli elementi del dashboard Real-Time una volta che sono sincronizzati con un repository GitHub o Azure DevOps.

Struttura di cartelle

Dopo aver sincronizzato un'area di lavoro con un repository, viene visualizzata una cartella di livello superiore per l'area di lavoro e una sottocartella per ogni elemento sincronizzato. Ogni sottocartella viene formattata con Nome elemento. Tipo di elemento

All'interno della cartella per il dashboard sono visualizzati i file seguenti:

Piattaforma: Definisce i valori della piattaforma fabric, come nome visualizzato e descrizione.
Proprietà: definisce valori specifici dell'elemento.

Ecco un esempio della struttura di cartelle:

Repository

Area di lavoro A
- Item_A.KQLDashboard
  - Piattaforma
  - RealTimeDashboard-1.json
Area di lavoro B
- Item_B.KQLDashboard
  - Piattaforma
  - RealTimeDashboard-2.json

Real-Time file del dashboard

I file seguenti sono contenuti in una cartella del dashboard:

.piattaforma

Il file usa lo schema seguente per definire un dashboard in tempo reale:

{
  "$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

Il file usa lo schema seguente per definire un dashboard in tempo reale:

{
  "$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": [
        "",
        ""
      ]
    }
  ]
}

Convalida in tempo reale del dashboard

L'endpoint di caricamento del dashboard Real-Time convalida il codice JSON oltre la conformità allo schema standard. Le violazioni vengono rilevate agli utenti nell'interfaccia utente del dashboard come messaggi di errore come: Error loading dashboard / Error found at: /<section> / Message: <reason>.

Unicità dei riferimenti di query

Ogni queryId sul dashboard deve essere referenziato esattamente una volta, conteggiato tra:

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

Se un queryId viene condiviso tra due riquadri, o tra un riquadro e una baseQuery, la convalida non riesce con: /queries: Some query IDs are used in multiple query references (tiles, base queries, parameters).

Quando si duplica un riquadro in una nuova pagina tramite codice, duplicare anche la query (assegnare un nuovo queryId, mantenere lo stesso text e dataSource) e collegare il queryRef.queryId del nuovo riquadro alla nuova query.

Univocità e formato id

Ogni id in tiles[], queries[], baseQueries[], parameters[], dataSources[] e pages[] deve essere:

Unico all'interno della categoria.
RFC 4122 UUID valido (ad esempio, 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a). Le stringhe leggibili con trattini ( ad esempio , my-tile-0001-0000-0000-000000000001) vengono rifiutate in fase di caricamento con: Needs to follow the UUID format as defined by RFC 4122.

Per le modifiche a livello di codice, generare ID con una libreria UUID: uuid.uuid4() per gli ID aggiornati o uuid.uuid5(namespace, label) per gli ID deterministici che sopravvivono alle riesecuzioni degli script.

Tip

Se viene visualizzato un errore di caricamento come /tiles/N/queryRef ... must have required property 'baseQueryId', l'effettivo errore è generalmente un queryRef.queryId malformato, non un baseQueryId mancante. Lo schema queryRef è un oggetto oneOf tra { kind: "query", queryId: <uuid> } e { kind: "baseQuery", baseQueryId: <uuid> }. Quando l'UUID interno non è valido, il validatore fallisce nel ramo query-kind e segnala gli errori dal ramo baseQuery-kind. Correggere l'UUID e le cancellate a catena.

Conservazione delle identità tra le modifiche

Per mantenere il collegamento tra il file e l'elemento dell'area di lavoro attiva, non modificare quanto segue nelle voci esistenti :

Livello superiore: id, eTag, schema_version
Per riquadro: id, pageId, queryRef.queryId
Per query: id, dataSource.dataSourceId
Per origine dati (dataSource): id, scopeId
Per pagina: id
Per parametro: id, variableName (e beginVariableName / endVariableName per kind: "duration")
.platform: config.logicalId

La modifica di questi identificatori porterà il cambiamento a essere considerato come un'eliminazione e una ricreazione alla successiva esecuzione di Update from Git, provocando la perdita di contesto: riferimenti agli elementi fissati, obiettivi di condivisione e qualsiasi stato collegato all'originale id.

Parameters

Quando un riquadro che usa un parametro (a cui viene fatto riferimento tramite la query usedVariables) viene aggiunto a una nuova pagina, tale parametro non viene visualizzato automaticamente nella nuova pagina. Se il parametro showOnPages.kind è "selection", è necessario aggiungere la nuova pagina id a showOnPages.pageIds. Se il parametro ha un valore utilizzabile defaultValue, il riquadro esegue il rendering con l'impostazione predefinita.

I parametri a più variabili come kind: "duration" i parametri espongono due variabili tramite beginVariableName e endVariableName (comunemente _startTime e _endTime). Condividono un singolo oggetto parametro con un'unica showOnPages impostazione.

Modifiche di esempio tramite Git

L'uso dello schema e delle note di convalida consente di apportare modifiche al dashboard Real-Time tramite Git anziché tramite l'interfaccia utente.

Esempio: Copiare un riquadro in una nuova pagina

Per copiare un riquadro dalla pagina A a una pagina B appena aggiunta modificando RealTimeDashboard-N.json:

Aggiungere la pagina B a pages[] con un nuovo id.
Copiare in modo approfondito il riquadro di origine in tiles[]. Assegnare:
- nuovo riquadro id (GUID aggiornato)
- pageId = ID pagina B
Trova la query di origine in queries[] in base al riquadro di origine queryRef.queryId.
Copia in modo approfondito la query in queries[] con un nuovo oggetto id.
Aggiornare il queryRef.queryId del riquadro clonato al id della nuova query.
Per ogni parametro a cui si fa riferimento nella query usedVariables[]clonata: se showOnPages.kind == "selection", aggiungere l'ID della pagina B a showOnPages.pageIds.
Verificare che non queryId venga visualizzato più di una volta in tiles[], baseQueries[]e parameters[].dataSource.queryRef.
Eseguire il commit, il push ed eseguire l'aggiornamento da Git nell'area di lavoro.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-04-28