Pulpit nawigacyjny w czasie rzeczywistym — integracja z usługą Git

W tym artykule szczegółowo opisuje strukturę folderów i plików dla elementów dashboardu Real-Time po zsynchronizowaniu z repozytorium GitHub lub Azure Devops.

Struktura folderów

Po zsynchronizowaniu obszaru roboczego z repozytorium zostanie wyświetlony folder najwyższego poziomu dla obszaru roboczego i podfolder dla każdego zsynchronizowanego elementu. Każdy podfolder jest sformatowany przy użyciu nazwy elementu. Typ elementu

W folderze pulpitu nawigacyjnego są widoczne następujące pliki:

Platforma: definiuje wartości platformy sieci szkieletowej, takie jak nazwa wyświetlana i opis.
Właściwości: definiuje wartości specyficzne dla elementu.

Oto przykład struktury folderów:

Repo

Obszar roboczy A
- Item_A.KQLDashboard
  - .platforma
  - RealTimeDashboard-1.json
Obszar roboczy B
- Item_B.KQLDashboard
  - .platforma
  - RealTimeDashboard-2.json

pliki dashboardu Real-Time

Następujące pliki znajdują się w folderze pulpitu nawigacyjnego:

.platforma

Plik używa następującego schematu do zdefiniowania pulpitu nawigacyjnego w czasie rzeczywistym:

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

Plik używa następującego schematu do zdefiniowania pulpitu nawigacyjnego w czasie rzeczywistym:

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

Sprawdzanie poprawności pulpitu nawigacyjnego w czasie rzeczywistym

Punkt końcowy ładowania danych pulpitu nawigacyjnego Real-Time weryfikuje JSON, sprawdzając zgodność wykraczającą poza standardowy schemat. Naruszenia są wyświetlane użytkownikom w interfejsie użytkownika pulpitu nawigacyjnego jako komunikaty o błędach, takie jak: Error loading dashboard / Error found at: /<section> / Message: <reason>.

Unikatowość odniesienia zapytań

Każdy queryId w pulpicie nawigacyjnym musi być referowany dokładnie raz, licząc w:

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

Jeśli element jest współużytkowany między dwoma queryId kafelkami lub między kafelkiem a zapytaniem podstawowym, walidacja kończy się niepowodzeniem w przypadku: /queries: Some query IDs are used in multiple query references (tiles, base queries, parameters).

Podczas duplikowania kafelka na nową stronę za pomocą oprogramowania, zduplikuj również zapytanie (przypisz nowe queryId, zachowaj to samo text i dataSource) i usuń wskaźnik nowego kafelka queryRef.queryId tak, aby wskazał na nowe zapytanie.

Unikatowość identyfikatorów i format

Każdy id w tiles[], queries[], baseQueries[], parameters[], dataSources[] i pages[] musi być:

Unikatowe w swojej kategorii.
Prawidłowy identyfikator UUID RFC 4122 (na przykład 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a). Ciągi czytelne, które mają kreski (np. my-tile-0001-0000-0000-000000000001), są odrzucane podczas ładowania: Needs to follow the UUID format as defined by RFC 4122.

W przypadku edycji programowych wygeneruj identyfikatory z biblioteką UUID: uuid.uuid4() dla nowych identyfikatorów lub uuid.uuid5(namespace, label) identyfikatorów deterministycznych, które przetrwają ponowne uruchamianie skryptu.

Wskazówka

Jeśli widzisz błąd ładowania, taki jak /tiles/N/queryRef ... must have required property 'baseQueryId', to faktyczną przyczyną jest zazwyczaj źle sformułowany queryRef.queryId, a nie brak baseQueryId. Schemat queryRef jest związkiem między oneOf a { kind: "query", queryId: <uuid> }. Jeśli wewnętrzny identyfikator UUID jest nieprawidłowy, walidator kończy wykonywanie gałęzi query-kind i zgłasza błędy z gałęzi baseQuery-kind. Napraw identyfikator UUID i usuń kaskadowe czyszczenia.

Zachowywanie tożsamości między edycjami

Aby zachować łącze między plikiem a elementem obszaru roboczego na żywo, nie należy modyfikować następujących elementów w istniejących wpisach:

Najwyższy poziom: id, eTag, schema_version
Na kafelek: id, pageId, queryRef.queryId
Na zapytanie: id, dataSource.dataSourceId
Według źródła danych: id, scopeId
Na stronę: id
Dla parametru: id, variableName (i beginVariableName / endVariableName dla kind: "duration")
.platform: config.logicalId

Zmodyfikowanie tych identyfikatorów spowoduje, że zmiana będzie traktowana jako usunięcie i ponowne utworzenie kolejnego elementu Update from Git, co spowoduje utratę kontekstu: przypięte odwołania do elementu, cele udostępniania oraz wszelkie stany dołączone do oryginalnego elementu id.

Parameters

Gdy kafelek używający parametru (przywoływany za pośrednictwem zapytania usedVariables) jest dodawany do nowej strony, ten parametr nie jest automatycznie wyświetlany na nowej stronie. Jeśli parametr ma wartość showOnPages.kind"selection", należy dołączyć id nowej strony do showOnPages.pageIds. Jeśli parametr ma wartość do użycia defaultValue, kafelek jest renderowany z wartością domyślną.

Parametry wielo zmienne, takie jak kind: "duration" parametry, uwidaczniają dwie zmienne za pomocą parametrów beginVariableName i endVariableName (często _startTime i _endTime). Współużytkują jeden obiekt parametru z jednym showOnPages ustawieniem.

Przykładowe edycje za pośrednictwem usługi Git

Korzystanie ze schematu i notatek weryfikacji umożliwia wprowadzanie zmian na pulpicie nawigacyjnym Real-Time za pośrednictwem usługi Git zamiast za pośrednictwem interfejsu użytkownika.

Przykład: Kopiowanie elementu kafelkowego na nową stronę

Aby skopiować kafelek ze strony A do nowo dodanej strony B, edytując RealTimeDashboard-N.json polecenie:

Dodaj stronę B do pages[] z nowym id elementem.
Skopiuj głęboko kafelek źródłowy w tiles[]. Przypisać:
- nowy kafelek id (nowy identyfikator GUID)
- pageId = identyfikator strony B
Znajdź zapytanie źródłowe w pliku queries[] według kafelka queryRef.queryIdźródłowego .
Skopiuj głęboko zapytanie do queries[] z nowym id.
Zaktualizuj queryRef.queryId sklonowanego kafelka, aby odpowiadał nowemu zapytaniu id.
Dla każdego parametru, do którego odwołuje się sklonowane zapytanieusedVariables[]: jeśli showOnPages.kind == "selection", dołącz identyfikator strony B do showOnPages.pageIds.
Sprawdź, czy żadne queryId nie pojawia się więcej niż raz w tiles[], baseQueries[] i parameters[].dataSource.queryRef.
Zatwierdź, wypchnij i uruchom Aktualizację z Git w obszarze roboczym.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-04-28