Vytvorte aplikáciu prepojenú so sémantickým modelom

Použite šablónu dátovej aplikácie s Fabric sémantickým modelovým konektorom na vytvorenie analytickej Fabric aplikácie. Šablóna poskytuje vizualizáciu, formátovanie, dátovú mriežku a vzory validácie v prehliadači. Konektor poskytuje typovaný, delegovaný prístup k sémantickému modelu prostredníctvom klienta Fabric Apps.

Aplikácie vytvorené pomocou šablóny hneď po vybalení zahŕňajú:

Fabric autentifikácia.
Kvalitnejšie usmernenie generovania DAX (Data Analysis Expressions).
Vizuálne komponenty pripravené pre podnik navrhnuté pre analytické aplikácie.
Dátová mriežka, témy, formátovanie a vzory validácie prehliadača.

Poznámka

V súčasnosti je podporovaným spôsobom vytvárania aplikácií pomocou šablóny dátovej aplikácie Rayfin CLI.

Prečo používať šablónu dátovej aplikácie?

Bez týchto zabudovaných schopností musí kódovací agent riešiť autentifikáciu, generovanie DAX a vizualizačný dizajn od nuly v každej relácii. To môže viesť k:

Viac zlyhaní a pokazené alebo prázdne vizuály.
Nekonzistentné správanie v horoskope.
Zbytočné DAX dotazy počas vývoja a behu.

Šablóna poskytuje opakovane použiteľné vzory, ktoré zvyšujú spoľahlivosť, vytvárajú súdržnejšie vizuály v súlade s najlepšími postupmi reportovania a znižujú režijné náklady na dotazy. Konektor štandardizuje konfiguráciu sémantických modelov a prístup za behu.

Predpoklady

Node.js 20 alebo neskôr.
Prístup k Fabric.
Fabric pracovný priestor, kde máte oprávnenia prispievateľa, člena alebo administrátora.
Záťaž Fabric Apps je zapnutá vo vašom tenante. Pozrite si aplikáciu Create your first Fabric.
Nastavenie nájomcu SEMANTIC Model Execute Queries REST API je zapnuté.
Build and Read oprávnenia na sémantický model hostovaný na kapacite Fabric alebo Power BI.
Workspace ID a item ID pre sémantický model.

Vytvorenie aplikácie

Vytvorte projekt z šablóny dátovej aplikácie:

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

Nahradte a použite <app-name><workspace-name> názvy pre vašu aplikáciu a Fabric workspace. Potom otvorte priečinok nového projektu:

cd <app-name>

Pridajte konektor sémantického modelu

Ak nepoznáte ID položky sémantického modelu, uveďte v pracovnom priestore sémantické modely:

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

Pridajte sémantický model ako spojku:

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

Príkaz:

Pridáva salesModel konektor k rayfin/rayfin.yml.
Vytvorí svoju schému pod .rayfin/connectors/salesModel/
Vytlačí príkaz zladený npm install s verziou pre balíky konektorov.

Spustite presný inštalačný príkaz vytlačený CLI.

Generovaná konfigurácia pripomína nasledujúci príklad:

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

Zachovaná je generovaná version hodnota.

Pripojte šablónu k sémantickému modelu

Šablóna obsahuje analytické komponenty a usmernenia pre agentov, ktoré môžete znovu použiť s konektorom. Nakonfigurujte jeho vrstvu prístupu k dátam tak, aby vytvorila a ConnectorsRayfinClient zaregistrovala runtime sémantického modelu:

Dôležité

Použite konektorového klienta na dotazy na sémantické modely. Ak scaffold obsahuje ďalšieho klienta sémantického modelu, namiesto udržiavania dvoch ciest prístupu k dátam nahraďte volania k nemu.

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(),
  }
);

Použite API URL a publikovateľný kľúč z vášho projektu Fabric Apps. Zachovajte existujúci Fabric prihlasovací tok šablóny.

Odoslať DAX cez konektor:

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);
}

Nahraďte Sales ju tabuľkou vo vašom sémantickom modeli. Skontrolujte vrátený stav predtým, než odovzdáte stĺpce a riadky do vizuálu.

Pre viac pokynov o konfigurácii konektorov a bezpečnosti pozri Connect Fabric Apps to Fabric data.

Vytvorte aplikáciu pomocou kódovacieho agenta

Lešenie obsahuje inštrukcie a zručnosti pre kódovacích agentov. Otvorte projekt vo vašom preferovanom agentovi a opísajte publikum, otázky, interakcie a vizualizácie aplikácie.

Môžete napríklad:

Otvorte projekt vo Visual Studio Code a potom otvorte panel GitHub Copilot Chat.
Otvorte terminál v projekte a potom spustite copilot.

Použite tento prompt ako východiskový bod:

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.

Použite možnosti šablóny

Šablóna dátovej aplikácie obsahuje opakovane použiteľné vzory pre analytické aplikácie.

Fabric Apps sú štandardné webové aplikácie, takže môžete implementovať funkcie mimo týchto vzorov. Funkcie, ktoré nie sú zahrnuté v šablóne, môžu vyžadovať viac vlastného inžinierstva a validácie.

Vizuály

Šablóna obsahuje krížové zvýrazňovanie a predkonfigurované primitíva pre:

Stĺpcové grafy, vrátane vertikálnych, horizontálnych, skupinových a stohovaných rozložení.
Čiarové grafy s voliteľnými značkami.
Mapy oblastí.
Bodové grafy.
Koláčové a donutové grafy.
Heatmapy.
Bublinové grafy.
Mapy vodopádov.
Karty s jednou hodnotou pre KPI výzvy.
Vrstvené a kompozitné vizuály, ako sú stĺpce s dátovými štítkami a dvojosové čiarové grafy.

Použite polia a miery, ktoré existujú v prepojenom sémantickom modeli. Nenahrádzajte dotaz na zlyhaný konektor mock dátami.

Môžete požiadať svojho kódovacieho agenta, aby generoval ďalšie vizuály. Vizuály bez šablónového primitívu môžu vyžadovať viac iterácií a overenia.

Schopnosti dátovej siete

Šablóna obsahuje dátovú mriežku s týmito predkonfigurovanými schopnosťami:

Hlavičky stĺpcov odvodené z metadát sémantického modelu.
Formátovanie čísla a dátumu aplikované na stĺpec cez formátovacie reťazce.
Triedenie.
Posúvateľné riadky s obsługou pretečenia.
Podpora svetlých a tmavých tém.
Vlastné cell renderery pre:
- Dátové stĺpce pre číselné hodnoty.
- Booleovské indikátory.
- Klikateľné URL.
- Obrazové bunky s prekrytím lightboxu.
- Viacpoľové bunky, napríklad meno a rola v jednom stĺpci.

Môžete pridať ďalšie možnosti dátovej siete, ale môžu vyžadovať viac vlastného inžinierstva.

Motívy

Stanovte svojmu kódovacemu agentovi požiadavky na značku alebo štýl, napríklad farebnú paletu, štýl rohov alebo písmo. Šablóna uchováva zdieľané štýly na jednom centrálnom mieste, takže zmeny sa prenášajú na karty, tlačidlá, grafy, dátové mriežky a tooltipy.

Centralizované štýlovanie zabraňuje nezhodným farbám, nekonzistentným fontom a rozdielom v rozložení, ktoré môžu nastať, keď je každý komponent štýlizovaný samostatne.

Formátovať reťazce

Definujte formátovanie raz na každý výsledkový stĺpec. Šablóna dokáže opätovne používať reťazce sémantických modelových formátov naprieč osami grafu, tooltipmi, dátovými štítkami, kartami a bunkami dátovej mriežky.

Napríklad definícia v jednom formáte zostáva zobrazená 1500.5 ako $1,500.50 a 0.25 zobrazená ako 25% všade tam, kde sa tieto hodnoty objavujú.

Overenie prehliadača

Pred zverejnením aplikácie použite priložený workflow Overovania prehliadača Playwright, aby ste ju otvorili v skutočnom prehliadači a skontrolujte:

Vizuály sa vykresľujú správne.
Grafy nie sú odrezané ani komprimované.
Text je čitateľný.
Dátové siete spracovávajú pretečenie.
Načítavanie, prázdne a chybové stavy sú použiteľné.
Filtre, krížové zvýrazňovanie a formátovanie dát fungujú podľa očakávaní.
Konzola prehliadača nemá žiadne neočakávané chyby.

Tento pracovný postup zachytí problémy s rozložením a vykresľovaním skôr, než ich používatelia uvidia. Overenie prehliadača potvrdzuje správanie frontendu. Otestujte nasadený konektor samostatne s používateľom, ktorý má prístup k aplikácii Fabric aj sémantickému modelu.

Nasadiť a overiť aplikáciu

Nasadenie aplikácie a konfigurácie konektora:

npx rayfin up

Otvorte nasadenú aplikáciu cez portál Fabric. Prihláste sa, spustite každú interakciu používateľa a porovnajte dôležité výsledky so sémantickým modelom.

Ak dotaz zlyhá:

Potvrďte ID pracovných priestorov a sémantických modelových položiek v rayfin.yml.
Potvrďte, že nastavenie nájomcu SEMANTIC Model Execute Queries REST API je zapnuté.
Potvrďte, že používateľ má na sémantický model oprávnenia Build and Read.
Overte, že DAX odkazuje na existujúce tabuľky, stĺpce a miery.
Skontrolujte kategóriu chyby a správu výsledku konektora.
Skontrolujte konzolu prehliadača na chyby na strane klienta.

Pripomienky

Bola táto stránka užitočná?

Naposledy aktualizované: 2026-09-29