Painel em tempo real – Integração do Git

Este artigo detalha a estrutura de pastas e arquivos para itens do painel Real-Time, uma vez que estão sincronizados com um repositório GitHub ou Azure DevOps.

Estrutura de pastas

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

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

Plataforma: define valores de plataforma de malha, como nome de exibição e descrição.
Propriedades: define valores específicos do item.

Aqui está um exemplo da estrutura de pastas:

Repositório

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

arquivos de dashboard Real-Time

Os seguintes arquivos estão contidos em uma pasta de 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 do painel em tempo real

O endpoint de carga do painel de Tempo Real valida o JSON além da conformidade com o esquema padrão. As violações aparecem para os usuários no painel como mensagens de erro como: Error loading dashboard / Error found at: /<section> / Message: <reason>.

Exclusividade da referência de consulta

Cada queryId item no painel deve ser referenciado exatamente uma vez, contado em:

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

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

Ao duplicar um bloco para uma nova página programaticamente, também duplique a consulta: atribua um novo queryId, mantenha o mesmo text e dataSource, e aponte o queryRef.queryId do novo bloco para a nova consulta.

Exclusividade e formato da ID

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

Exclusivo dentro de sua categoria.
Um RFC 4122 UUID válido (por exemplo, 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a). Cadeias de caracteres legíveis que têm traços (por exemplo, my-tile-0001-0000-0000-000000000001) são rejeitadas no tempo de 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 novas ou uuid.uuid5(namespace, label) para IDs determinísticas que sobrevivem a execuções de script.

Dica

Se você vir um erro de carga como /tiles/N/queryRef ... must have required property 'baseQueryId', a falha real geralmente é uma malformação queryRef.queryId, e não a ausência de 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 no ramo do tipo query e relata falhas do ramo do tipo baseQuery. Corrija o UUID e as operações de limpeza em cascata.

Preservação de identidade entre edições

Para preservar o link entre o arquivo e o objeto ativo do workspace, não modifique o seguinte nas entradas existentes:

Nível superior: id, , eTagschema_version
Por bloco: id, pageId, queryRef.queryId
Por consulta: id, dataSource.dataSourceId
Por meio de dataSource: id, scopeId
Por página: id
Por parâmetro: id, variableName (e beginVariableName / endVariableName para kind: "duration")
.platform: config.logicalId

Modificar esses identificadores faz com que a alteração seja considerada como uma exclusão e uma recriação na próxima Update from Git, o que causará a perda de contexto: referências de itens fixados, destinos de compartilhamento e qualquer estado anexado ao original id.

Parameters

Quando um bloco que usa um parâmetro (referenciado por meio da usedVariablesconsulta) é 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", você precisará acrescentar a nova página id a showOnPages.pageIds. Se o parâmetro tiver um defaultValue válido, o tile será renderizado com o padrão.

Parâmetros de várias variáveis, como kind: "duration" parâmetros, expõem duas variáveis por meio beginVariableName e endVariableName (normalmente _startTime e _endTime). Eles compartilham um único objeto de parâmetro com uma showOnPages configuração.

Edições de exemplo via Git

Usar as notas de esquema e validação permite que você faça alterações no painel de Real-Time por meio do Git, em vez de por meio da interface do usuário.

Exemplo: copiar um bloco para uma nova página

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

Adicionar a página B a pages[] com um novo id.
Copie profundamente o tile de origem em tiles[]. Atribuir:
- novo bloco id (GUID novo)
- pageId = ID da página B
Localize a consulta de fonte no queries[] pelo bloco de fonte queryRef.queryId.
Faça uma cópia profunda da consulta em queries[] utilizando um novo id.
Atualize o queryRef.queryId dos blocos clonados para o id da nova consulta.
Para cada parâmetro referenciado na consulta clonada: usedVariables[]se showOnPages.kind == "selection", acrescente a ID da página B a showOnPages.pageIds.
Valide que queryId não aparece mais de uma vez entre tiles[], baseQueries[] e parameters[].dataSource.queryRef.
Confirme, faça push e execute a Atualização do Git no espaço de trabalho.

Comentários

Esta página foi útil?

Last updated on 2026-04-28