Painel em tempo real - Integração com Git

Este artigo detalha a estrutura de pastas e arquivos para itens do dashboard Real-Time após serem sincronizados com um repositório do GitHub ou Azure DevOps.

Estrutura de pastas

Depois que um espaço de trabalho é sincronizado com um repositório, você vê uma pasta de nível superior para o espaço de trabalho e uma subpasta para cada item que foi sincronizado. Cada subpasta é formatada com Nome do Item. Tipo de Item

Dentro da pasta do painel, você verá os seguintes arquivos:

Plataforma: Define os valores da plataforma de estrutura, como o nome a exibir e a descrição.
Propriedades: Define valores específicos do item.

Aqui está um exemplo da estrutura de pastas:

Repositório

Espaço de trabalho A
- Item_A.KQLDashboard
  - .plataforma
  - RealTimeDashboard-1.json
Espaço de trabalho B
- Item_B.KQLDashboard
  - .plataforma
  - RealTimeDashboard-2.json

arquivos do painel Real-Time

Os seguintes arquivos estão contidos em uma pasta do painel:

.plataforma

O arquivo usa o seguinte esquema para definir um painel em tempo 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

O arquivo usa o seguinte esquema para definir um painel em tempo 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": [
        "",
        ""
      ]
    }
  ]
}

Validação de dashboards em tempo real

O endpoint de carga do Real-Time Dashboard valida o JSON para além da conformidade padrão do esquema. As violações aparecem para os utilizadores na interface do painel sob a forma de mensagens de erro como: Error loading dashboard / Error found at: /<section> / Message: <reason>.

Unicidade de referência de consulta

Cada um no painel queryId deve ser referenciado uma única vez, contado em todo o âmbito de:

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

Se um queryId for compartilhado entre dois blocos, ou entre um bloco e uma baseQuery, então a validação falha com: /queries: Some query IDs are used in multiple query references (tiles, base queries, parameters).

Ao duplicar um tile para uma nova página programaticamente, também deve duplicar a consulta (atribuir uma nova queryId, manter o mesmo text e dataSource) e apontar o queryRef.queryId do novo tile para a nova consulta.

Singularidade e formato do ID

Todo id em tiles[], queries[], baseQueries[], parameters[], dataSources[], , e pages[] deve ser:

Único dentro da sua categoria.
Um UUID válido do RFC 4122 (por exemplo, 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a). Cadeias legíveis que por acaso têm traços (por exemplo, my-tile-0001-0000-0000-000000000001) são rejeitadas durante o carregamento com: Needs to follow the UUID format as defined by RFC 4122.

Para edições programáticas, gere IDs com uma biblioteca UUID: uuid.uuid4() para IDs novos, ou uuid.uuid5(namespace, label) para IDs determinísticos que sobrevivam a repetições de scripts.

Tip

Se observar um erro de carga como /tiles/N/queryRef ... must have required property 'baseQueryId', a falha real é geralmente um queryRef.queryId malformado, não a falta de um baseQueryId. O esquema queryRef é um oneOf entre { kind: "query", queryId: <uuid> } e { kind: "baseQuery", baseQueryId: <uuid> }. Quando o UUID interno é inválido, o validador falha o tipo de ramo query e reporta falhas do tipo de ramo baseQuery em vez disso. Corrige o UUID e a cascata limpa.

Preservação da identidade durante edições

Para preservar a ligação entre o ficheiro e o item do espaço de trabalho ao vivo, não modifique o seguinte nas entradas existentes :

Nível superior: id, eTag, schema_version
Por peça: id, pageId, queryRef.queryId
Por consulta: id, dataSource.dataSourceId
Para cada dataSource: id, scopeId
Por página: id
Por parâmetro: id, variableName (e beginVariableName / endVariableName para kind: "duration")
.platform: config.logicalId

Modificar estes identificadores fará com que a alteração seja tratada como uma eliminação e uma recriação no próximo Update from Git, o que causará perda de contexto: referências a itens fixados, alvos de partilha e qualquer estado associado ao original id.

Parameters

Quando um tile que usa um parâmetro (referenciado através da consulta usedVariables) é adicionado a uma nova página, esse parâmetro não aparece automaticamente na nova página. Se o parâmetro showOnPages.kind for "selection", precisa de adicionar a nova página id a showOnPages.pageIds. Se o parâmetro tiver um defaultValue válido, então o azulejo é desenhado com o padrão.

Parâmetros multivariáveis como kind: "duration" parâmetros expõem duas variáveis via beginVariableName e endVariableName (comumente _startTime e _endTime). Partilham um objeto de parâmetro único com uma showOnPages definição.

Exemplos de edições via Git

Usar as notas de esquema e validação permite-lhe fazer alterações ao painel de Real-Time via Git em vez de através da interface de utilizador.

Exemplo: Copiar um bloco para uma nova página

Para copiar um mosaico da página A para uma página B recém-adicionada editando RealTimeDashboard-N.json:

Adicionar a página B ao pages[] com um novo id.
Faça uma cópia profunda do tile de origem em tiles[]. Atribuição:
- novo bloco id (GUID novo)
- pageId = ID da página B
Encontre a consulta de origem em queries[] através do tile de origem queryRef.queryId.
Copie profundamente a consulta para queries[] com um novo id.
Atualize o queryRef.queryId do bloco clonado para o id da nova consulta.
Para cada parâmetro referenciado na consulta usedVariables[]clonada : se showOnPages.kind == "selection", adicione o ID da página B a showOnPages.pageIds.
Valide que queryId não aparece mais do que uma vez em tiles[], baseQueries[], e parameters[].dataSource.queryRef.
Envia um commit, faz push e executa a atualização do Git no workspace.

Comentários

Esta página foi útil?

Last updated on 2026-04-28