Panel en tiempo real: integración de Git

En este artículo se detalla la estructura de carpetas y archivos de Real-Time elementos del panel una vez que se sincronizan con un repositorio de GitHub o Azure Devops.

Estructura de carpetas

Una vez que se sincroniza un área de trabajo con un repositorio, verá una carpeta de nivel superior para el área de trabajo y una subcarpeta para cada elemento que se sincronizó. Cada subcarpeta tiene el formato Nombre del elemento. Tipo de elemento

En la carpeta del panel, verá los siguientes archivos:

Plataforma: define valores de la plataforma, como el nombre para mostrar y la descripción.
Propiedades: define valores específicos del elemento.

Este es un ejemplo de la estructura de carpetas:

repo

Área de trabajo A
- Item_A.KQLDashboard
  - .plataforma
  - RealTimeDashboard-1.json
Área de trabajo B
- Item_B.KQLDashboard
  - .plataforma
  - RealTimeDashboard-2.json

Real-Time archivos de tablero de mandos

Los archivos siguientes se encuentran en una carpeta de panel:

.plataforma

El archivo usa el esquema siguiente para definir un panel en tiempo real:

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

El archivo usa el esquema siguiente para definir un panel en tiempo real:

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

Validación del tablero de tiempo real

El punto de conexión de carga del panel de Real-Time valida el JSON más allá de la conformidad del esquema estándar. Las infracciones se muestran a los usuarios de la interfaz de usuario del panel como mensajes de error como: Error loading dashboard / Error found at: /<section> / Message: <reason>.

Unicidad de referencia de consulta

Se debe hacer referencia a cada queryId del panel de control exactamente una vez, contabilizado en:

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

queryId Si un objeto se comparte entre dos iconos o entre un icono y una baseQuery, se produce un error de validación con: /queries: Some query IDs are used in multiple query references (tiles, base queries, parameters).

Al duplicar un icono en una nueva página mediante programación, duplique también la consulta (asigne un nuevo queryId, mantenga el mismo text y dataSource) y apunte el icono nuevo queryRef.queryId en la nueva consulta.

Unicidad y formato de identificador

Cada id en tiles[], queries[], baseQueries[], parameters[], dataSources[], y pages[] debe ser:

Único dentro de su categoría.
Un UUID RFC 4122 válido (por ejemplo, 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a). Las cadenas legibles que contienen guiones (por ejemplo, my-tile-0001-0000-0000-000000000001) serán rechazadas al momento de la carga con: Needs to follow the UUID format as defined by RFC 4122.

Para las ediciones mediante programación, genere identificadores con una biblioteca UUID: uuid.uuid4() para identificadores nuevos o uuid.uuid5(namespace, label) para identificadores deterministas que sobreviven a las repeticiones de scripts.

Sugerencia

Si ve un error de carga como /tiles/N/queryRef ... must have required property 'baseQueryId', la falla real suele ser un queryRef.queryId malformado, no una falta de baseQueryId. El esquema queryRef es un oneOf entre { kind: "query", queryId: <uuid> } y { kind: "baseQuery", baseQueryId: <uuid> }. Cuando el UUID interno no es válido, el validador falla la rama query-kind y notifica errores de la rama baseQuery-kind en su lugar. Corrija el UUID y las eliminaciones en cascada.

Conservación de identidades en ediciones

Para conservar el vínculo entre el archivo y el elemento del área de trabajo activa, no modifique lo siguiente en las entradas existentes :

Nivel superior: id, eTag, schema_version
Por icono: id, , pageIdqueryRef.queryId
Por cada consulta: id, dataSource.dataSourceId
Por origen de datos: id, scopeId
Por página: id
Por parámetro: id, variableName (y beginVariableName / endVariableName para kind: "duration")
.platform: config.logicalId

La modificación de estos identificadores hará que el cambio se trate como una eliminación y una nueva creación en el siguiente Update from Git, lo que provocará la pérdida de contexto: referencias de elementos anclados, destinos de compartición y cualquier estado vinculado al original id.

Parameters

Cuando se agrega un icono que usa un parámetro (al que se hace referencia a través de usedVariablesla consulta ) a una página nueva, ese parámetro no aparece automáticamente en la nueva página. Si el parámetro showOnPages.kind es "selection", debe anexar el id de la nueva página a showOnPages.pageIds. Si el parámetro tiene un valor utilizable defaultValue, el icono se representa con el valor predeterminado.

Los parámetros de varias variables como kind: "duration" exponen dos variables, por beginVariableName y endVariableName (normalmente _startTime y _endTime). Comparten un único objeto de parámetros con una única showOnPages configuración.

Modificaciones de ejemplo a través de Git

El uso del esquema y las notas de validación permite realizar cambios en el panel de Real-Time a través de Git en lugar de a través de la interfaz de usuario.

Ejemplo: Copiar un icono en una nueva página

Para copiar un icono de la página A a una página B recién agregada editando RealTimeDashboard-N.json:

Agregue la página B a pages[] con un nuevo id.
Copie en profundidad el icono de origen en tiles[]. Asignar:
- nuevo icono id (GUID nuevo)
- pageId = id. de la página B
Busque la consulta de origen en queries[] por el icono de queryRef.queryIdorigen.
Realice una copia profunda de la consulta en queries[] con un nuevo id.
Actualice el cuadro queryRef.queryId clonado con la nueva consulta id.
Para cada parámetro al que se hace referencia en la consulta usedVariables[]clonada: si showOnPages.kind == "selection", anexa el identificador de la página B a showOnPages.pageIds.
Compruebe que no queryId aparece más de una vez en tiles[], baseQueries[]y parameters[].dataSource.queryRef.
Confirme, empuje y ejecute Actualización desde Git en el área de trabajo.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-04-28