Tworzenie aplikacji połączonej z modelem semantycznym

Użyj szablonu aplikacji danych z konektorem semantycznych modeli Fabric, aby zbudować aplikację analityczną Fabric. Szablon zapewnia wizualizację, formatowanie, siatkę danych oraz wzorce walidacji w przeglądarce. Konektor zapewnia typowany, delegowany dostęp do modelu semantycznego za pośrednictwem klienta Fabric Apps.

Gotowe aplikacje utworzone za pomocą szablonu obejmują:

Uwierzytelnianie w usłudze Fabric.
Wyższej jakości wytyczne dotyczące generowania DAX (Data Analysis Expressions).
Komponenty wizualne gotowe do zastosowań korporacyjnych, przeznaczone do aplikacji analitycznych.
Siatka danych, tematyka, formatowanie oraz wzorce walidacji w przeglądarce.

Uwaga / Notatka

Obecnie obsługiwanym sposobem tworzenia aplikacji jest CLI Rayfin za pomocą szablonu aplikacji danych.

Dlaczego warto używać szablonu aplikacji danych?

Bez tych wbudowanych możliwości agent kodujący musi od podstaw rozwiązywać uwierzytelnianie, generowanie DAX i projektowanie wizualizacji w każdej sesji. To może prowadzić do:

Kolejne porażki i zepsute lub puste wizualizacje.
Niespójne zachowanie wykresu.
Niepotrzebne zapytania DAX podczas programowania i w czasie wykonywania.

Szablon oferuje wielokrotnego użytku wzorce, które poprawiają niezawodność, tworzą bardziej spójne wizualizacje zgodne z najlepszymi praktykami raportowania oraz zmniejszają narzut zapytań. Konektor standaryzuje konfigurację modelu semantycznego i dostęp do czasu działania.

Wymagania wstępne

Node.js 20 lub nowszy.
Dostęp do Fabric.
Obszar roboczy Fabric, w którym masz uprawnienia Współautor, Członek lub Administrator.
Funkcja Fabric Apps włączona w Twojej dzierżawie. Zobacz Stwórz swoją pierwszą aplikację Fabric.
Ustawienie dzierżawy interfejsu API REST wykonywania zapytań semantycznego modelu jest włączone.
Uprawnienia do kompilowania i odczytu modelu semantycznego hostowanego w usłudze Fabric lub w pojemności usługi Power BI.
ID przestrzeni roboczej i ID elementu dla modelu semantycznego.

Tworzenie aplikacji

Stwórz projekt na podstawie szablonu aplikacji danych:

npm create @microsoft/rayfin@latest -- "<app-name>" --template dataapp --workspace <workspace-name>

Zastąp <app-name> i <workspace-name> nazwami swojej aplikacji i obszaru roboczego Fabric. Następnie otwórz folder nowego projektu:

cd <app-name>

Dodaj złącze modelu semantycznego

Jeśli nie znasz ID pozycji modelu semantycznego, wypisz modele semantyczne w przestrzeni roboczej:

npx rayfin connector search --workspace-id <workspace-id> --type fabric-semanticmodel --json

Dodaj model semantyczny jako łącznik:

npx rayfin connector add --type fabric-semanticmodel --workspace-id <workspace-id> --item-id <semantic-model-item-id> --name salesModel --operations executeQuery

Polecenie:

Dodaje złącze salesModel do rayfin/rayfin.yml.
Tworzy swój schemat pod rayfin/connectors/salesModel/.
Wyświetla polecenie npm install odpowiadające wersji pakietów konektora.

Uruchom dokładne polecenie instalacyjne wydrukowane przez CLI.

Wygenerowana konfiguracja przypomina następujący przykład:

connectors:
  - name: salesModel
    type: fabric-semanticmodel
    config:
      workspaceId: "<workspace-id>"
      itemId: "<semantic-model-item-id>"
    auth:
      type: delegated
    version: "1"
    operations:
      - name: executeQuery

Zachowaj wygenerowaną version wartość.

Połącz szablon z modelem semantycznym

Szablon zawiera komponenty analityczne i wskazówki dla agentów, które można ponownie wykorzystać z łącznikiem. Konfiguruj jego warstwę dostępu do danych, aby utworzyła ConnectorsRayfinClient i zarejestrowała czas działania modelu semantycznego:

Important

Użyj klienta connector do zapytań o model semantyczny. Jeśli szkielet zawiera innego klienta modelu semantycznego, zastąp nim wywołania zamiast utrzymywać dwa sposoby dostępu do danych.

import { ConnectorsRayfinClient } from '@microsoft/rayfin-client';
import { fabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
import {
  connectorConfig,
  type SalesModelSchema,
} from '../../rayfin/connectors/salesModel/schema.js';

type AppConnectorsSchema = {
  salesModel: SalesModelSchema;
};

export const client = new ConnectorsRayfinClient<
  Record<string, never>,
  Record<string, never>,
  AppConnectorsSchema
>(
  {
    baseUrl: '<app-api-url>',
    publishableKey: '<publishable-key>',
    authStorage: true,
    connectors: {
      salesModel: connectorConfig,
    },
  },
  {
    salesModel: fabricSemanticModel(),
  }
);

Użyj adresu URL API i klucza publikowalnego z projektu Fabric Apps. Zachowaj istniejący przepływ logowania Fabric w szablonie.

Przesłaj DAX przez złącze:

const result = await client.connectors.salesModel.executeQuery({
  query: 'EVALUATE TOPN(10, Sales)',
});

if (result.status === 'success') {
  console.log(result.table.columns, result.table.rows);
} else {
  console.error(result.error.category, result.error.message);
}

Zastąp Sales tabelą w modelu semantycznym. Sprawdź status zwracanych danych przed przekazaniem kolumn i wierszy do wizualizatora.

Aby uzyskać więcej wskazówek dotyczących konfiguracji złączy i bezpieczeństwa, zobacz Connect Fabric Apps to Fabric data.

Zbuduj aplikację z pomocą agenta kodującego

Szkielet zawiera instrukcje i umiejętności dla agentów programistycznych. Otwórz projekt w wybranym przez siebie agenta i opisz odbiorców, pytania, interakcje oraz wizualizacje aplikacji.

Możesz na przykład:

Otwórz projekt w Visual Studio Code, a następnie otwórz panel GitHub Copilot Chat.
Otwórz terminal w projekcie, a następnie uruchom copilot.

Użyj tego promptu jako punktu wyjścia:

Build an analytical Fabric app that uses the existing salesModel connector.

Before editing:
1. Read the repository instructions and skills.
2. Inspect rayfin/connectors/salesModel/schema.ts and the template's data-access,
   visualization, data grid, formatting, and validation patterns.
3. Query the semantic model metadata before writing DAX. Don't guess table,
   measure, or column names.

Requirements:
- Use ConnectorsRayfinClient and fabricSemanticModel() for semantic model access.
- Call client.connectors.salesModel.executeQuery() for DAX queries.
- Keep the existing Fabric sign-in flow. Don't add credentials, access tokens,
  another authentication flow, or direct calls to the Execute Queries REST API.
- Reuse query results where practical, and bound large result sets.
- Apply semantic model format strings consistently to cards, charts, tooltips,
  and data grids.
- Include loading, empty, and error states.
- Use the template's browser-validation workflow at desktop and mobile sizes.

Give me a short implementation plan, make the changes, run the existing build,
and report the results.

Wykorzystaj możliwości szablonu

Szablon aplikacji danych zawiera wzorce wielokrotnego użytku do zastosowań analitycznych.

Fabric Apps to standardowe aplikacje webowe, więc możesz implementować funkcje poza tymi wzorcami. Funkcje, które nie są uwzględnione w szablonie, mogą wymagać więcej niestandardowej inżynierii i weryfikacji.

Wizualizacje

Szablon zawiera krzyżowe podświetlanie i wstępnie skonfigurowane prymitywy dla:

Wykresy słupkowe, w tym układy pionowe, poziome, grupowane i ułożone.
Wykresy liniowe z opcjonalnymi znacznikami.
Mapy obszarowe.
Wykresy rozrzutowe.
Wykresy ciast i pączków.
Mapy cieplne.
Wykresy bąbelkowe.
Wykresy wodospadów.
Karty o pojedynczych wartościach do wywołań KPI.
Warstwowe i kompozytowe wizualizacje, takie jak słupki z etykietami danych i wykresy liniowe z dwoma osiami.

Używaj pól i miar istniejących w połączonym modelu semantycznym. Nie zastępuj nieudanego zapytania łącznika danymi pozorowanymi.

Możesz poprosić swojego agenta programistycznego o wygenerowanie innych wizualizacji. Wizualizacje bez szablonu prymitywnego mogą wymagać więcej iteracji i weryfikacji.

Możliwości siatki danych

Szablon zawiera siatkę danych z tymi wstępnie skonfigurowanymi funkcjami:

Nagłówki kolumn pochodzą z metadanych modelu semantycznego.
Formatowanie liczb i dat stosowanych w kolumnach za pomocą ciągów formatowych.
Sortowanie.
Przewijane wiersze z obsługą przepełnienia.
Wsparcie dla jasnych i ciemnych motywów.
Niestandardowe mechanizmy renderowania komórek dla:
- Paski danych dla wartości liczbowych.
- Wskaźniki boole'a.
- Klikalne adresy URL.
- Komórki z obrazami z nakładką typu lightbox.
- Komórki z wieloma polami, takie jak nazwa i rola w jednej kolumnie.

Możesz dodać inne funkcje siatki danych, ale mogą one wymagać dodatkowych niestandardowych prac programistycznych.

Motywy

Określ swojemu agentowi kodującego wymagania dotyczące marki lub stylizacji, takie jak paleta kolorów, styl narożników czy czcionka. Szablon utrzymuje wspólne style w jednym centralnym miejscu, więc zmiany przechodzą do kart, przycisków, wykresów, siatek danych i podpowiedzi.

Scentralizowane stylizowanie pozwala uniknąć niedopasowanych kolorów, niespójnych czcionek oraz różnic w układzie, które mogą wystąpić, gdy każdy komponent jest stylizowany osobno.

Formatuj ciągi

Definiuj formatowanie raz na kolumnę wyników. Szablon może ponownie wykorzystywać ciągi formatów semantycznych modeli na osiach wykresu, podpowiedzi, etykietach danych, kartach oraz komórkach siatki danych.

Na przykład pojedyncza definicja formatu sprawia, że 1500.5 jest wyświetlane jako $1,500.50, a 0.25 jako 25% wszędzie tam, gdzie te wartości występują.

Walidacja przeglądarki

Przed opublikowaniem aplikacji użyj dołączonego przepływu pracy Playwright do sprawdzania w przeglądarce, aby otworzyć ją w rzeczywistej przeglądarce i sprawdzić:

Wizualizacje są poprawnie odwzorowane.
Wykresy nie są odcięte ani kompresowane.
Tekst jest czytelny.
Siatki danych obsługują przepełnienie.
Stany ładowania, pustego ekranu i błędu są użyteczne.
Filtry, krzyżowe podświetlanie i formatowanie danych działają zgodnie z oczekiwaniami.
Konsola przeglądarki nie ma żadnych nieoczekiwanych błędów.

Ten workflow wykrywa problemy z układem i renderowaniem, zanim użytkownicy je zauważą. Walidacja w przeglądarce potwierdza zachowanie warstwy front-endowej. Przetestuj wdrożony konektor osobno z użytkownikiem, który ma dostęp zarówno do aplikacji Fabric, jak i modelu semantycznego.

Wdroż i zweryfikowaj aplikację

Wdrożenie aplikacji i konfiguracji złącza:

npx rayfin up

Otwórz wdrożoną aplikację z portalu Fabric. Zaloguj się, uruchom każdą interakcję użytkownika i porównaj ważne wyniki z modelem semantycznym.

Jeśli zapytanie się nie powiedzie:

Potwierdź identyfikator obszaru roboczego i identyfikator elementu modelu semantycznego w rayfin.yml.
Potwierdź, że ustawienie Semantic Model Execute Queries REST API jest włączone.
Potwierdź, że użytkownik ma uprawnienia do budowania i odczytu w modelu semantycznym.
Sprawdź, czy DAX odnosi się do istniejących tabel, kolumn i miar.
Sprawdź kategorię błędu i komunikat wyniku łącznika.
Sprawdź konsolę przeglądarki pod kątem błędów po stronie klienta.

Opinia

Czy ta strona była pomocna?

Ostatnia aktualizacja o 2026-09-29