Szemantikai modellhez csatlakoztatott alkalmazás létrehozása

Használd az adatalkalmazás sablont egy Fabric szemantikai modell csatlakozóval, hogy elkészíts egy analitikus Fabric alkalmazást. A sablon vizualizációt, formázást, adatrácsot és böngésző-validációs mintákat biztosít. A csatlakozó gépelt, delegált hozzáférést biztosít egy szemantikai modellhez a Fabric Apps kliensen keresztül.

A sablonnal létrehozott alkalmazások a következők:

  • Fabric hitelesítés.
  • Magasabb minőségű DAX (Data Analysis Expressions) generálási útmutató.
  • Vállalati kész vizuális komponensek, amelyeket analitikai alkalmazásokhoz terveztek.
  • Adatrács, témázás, formázás és böngészőalapú ellenőrzési minták.

Megjegyzés:

Jelenleg a Rayfin CLI a támogatott módja az alkalmazások létrehozásának az adatalkalmazás sablon használatával.

Miért érdemes az adatalkalmazás-sablont használni?

Ezek nélkül a beépített képességek nélkül egy kódoló ügynöknek minden alkalommal a nulláról kell megoldania a hitelesítést, DAX generálást és vizualizációs tervezést. Ez vezethet a következőkhöz:

  • Több kudarc, törött vagy üres vizuális megjelenítés.
  • A diagram viselkedése következetlen.
  • Felesleges DAX lekérdezések fejlesztés és futás közben.

A sablon újrahasználható mintákat kínál, amelyek növelik a megbízhatóságot, kohérensebb vizuális megjelenítéseket hoznak létre a legjobb jelentési gyakorlatokhoz igazítva, és csökkentik a lekérdezési terhelést. A csatlakozó szabványosítja a szemantikai modell konfigurációját és a futásidejű hozzáférést.

Prerequisites

  • Node.js 20 vagy újabb.
  • Hozzáférés a Fabric.
  • Egy Fabric munkaterület, ahol közreműködői, tagi vagy rendszergazdai engedélyekkel rendelkezik.
  • Az Ön bérlőjében engedélyezett Fabric Apps-munkaterhelés. Lásd: Készítsd meg az első Fabric alkalmazásodat.
  • A szemantikai modell lekérdezések végrehajtása REST API-bérlőbeállítás engedélyezve van.
  • Építsd és olvasd el a jogosultságokat egy szemantikai modellen, amely Fabric vagy Power BI kapacitáson hosztozott.
  • A szemantikai modell munkaterület azonosítója és elemazonosítója.

Az alkalmazás létrehozása

Hozz létre egy projektet az adatalkalmazás sablonból:

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

Cseréld le a(z) <app-name> és <workspace-name> elemeket az alkalmazásod és a Fabric-munkaterületed nevére. Ezután nyisd meg az új projektmappát:

cd <app-name>

Adjunk hozzá a szemantikai modellcsatlakozót

Ha nem ismered a szemantikai modellelem azonosítóját, sorold fel a szemantikus modelleket a munkaterületen:

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

Adjunk hozzá a szemantikai modellt csatlakozóként:

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

A parancs:

  • Hozzáadja a(z) salesModel csatlakozót a következőhöz: rayfin/rayfin.yml.
  • Létrehozza a sémát a(z) rayfin/connectors/salesModel/ alatt.
  • A csatlakozó csomagokhoz verzióhoz igazított npm install parancsot nyomtat.

Futtassa pontosan a CLI által kiírt telepítési parancsot.

A generált konfiguráció a következő példára hasonlít:

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

Tartsd meg a generált version értéket.

Kapcsold össze a sablont a szemantikai modellhez

A sablon elemző összetevőket és ügynöki útmutatást tartalmaz, amelyek a csatlakozóval újra felhasználhatók. Konfigurálja az adathozzáférési rétegét egy ConnectorsRayfinClient létrehozásához és a szemantikai modell futtatókörnyezetének regisztrálásához:

Important

Használd a connector klienst szemantikai modell lekérdezésekhez. Ha a sablon tartalmaz egy másik szemantikai modellklienst, a két adathozzáférési útvonal fenntartása helyett cserélje le az arra irányuló hívásokat.

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

Használd az API URL-t és a publikálható kulcsot a Fabric Apps projektedből. Tartsd meg a sablon meglévő Fabric bejelentkezési folyamatát.

Küldd be a DAX-ot a csatlakozón keresztül:

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

Cseréld Sales le táblázatot a szemantikai modelledben. Ellenőrizd a visszaküldött státuszt, mielőtt oszlopokat és sorokat átadsz egy vizualizációnak.

További csatlakozó konfigurációért és biztonsági útmutatóért lásd: Connect Fabric Apps to Fabric data.

Készítsd az alkalmazást egy kódoló ügynökkel

A váz utasításokat és készségeket tartalmaz a kódoló ügynökök számára. Nyisd meg a projektet a kedvenc ügynöködben, és írd le az alkalmazás közönségét, kérdéseket, interakcióit és vizualizációit.

Például megteheted a következőket:

  • Nyisd meg a projektet a Visual Studio Code-ban, majd nyisd meg a GitHub Copilot Chat panelt.
  • Nyiss meg egy terminált a projektben, majd futtasd copilot.

Képernyőkép a GitHub Copilot Chat interfészt mutatja a Visual Studio Code-ban.

Használd ezt a promptot kiindulópontként:

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.

Használja a sablon képességeket

Az adatalkalmazás sablon újrahasználható mintákat tartalmaz analitikai alkalmazásokhoz.

A Fabric-alkalmazások szabványos webalkalmazások, így ezeken a mintákon kívül eső funkciókat is megvalósíthat. Olyan funkciók, amelyek nincsenek benne a sablonban, több egyedi mérnöki beavatkozást és validációt igényelhetnek.

Vizualizációk

A sablon keresztkiemelést és előre konfigurált primitíveket tartalmaz a következőkhöz:

  • Oszlopdiagramok, beleértve a függőleges, vízszintes, csoportosított és egymásra rakott elrendezéseket.
  • Vonaldiagramok opcionális jelölőkkel.
  • Területi térképek.
  • Szórványdiagramok.
  • Pite és fánkos táblázatok.
  • Hőtérképek.
  • Buborékdiagramok.
  • Vízesési térképek.
  • Egyetlen értéket megjelenítő kártyák KPI-kiemelésekhez.
  • Réteges és összetett vizuális elemek, például sávok adatcímkékkel és kéttengelyes vonaldiagramok.

Használd azokat a mezőket és mértékeket, amelyek a kapcsolt szemantikai modellben léteznek. Ne cserélj egy sikertelen csatlakozó lekérdezést mock adattal.

Megkérheted a kódoló ügynöködet, hogy generáljon más vizuális anyagokat. Sablonprimitív nélküli vizualizációk több iterációt és validációt igényelhetnek.

Az adatrács funkciói

A sablon tartalmaz egy adatrácsot az alábbi előre konfigurált képességekkel:

  • Oszlopfejlécek szemantikai modell metaadatokból származnak.
  • A szám- és dátumformázást oszloponként alkalmazzák formátumi láncokon keresztül.
  • Válogatás.
  • Görgethető sorok túlcsorduláskezeléssel.
  • Világos és sötét téma támogatás.
  • Egyedi cella renderelők a következőkhöz:
    • Adatsávok számértékekhez.
    • Boolean mutatók.
    • Kattintható URL-ek.
    • Képcellák fénydoboz réteggel.
    • Többmezős cellák, például egy név és szerep egy oszlopban.

Hozzáadhatsz más adatrács képességeket, de ezek több egyedi mérnöki munkát igényelhetnek.

Témázás

Határozz meg kódolóügynöködnek márkajelzési vagy stílusbeli követelményeket, például színpalettát, sarokstílust vagy betűtípust. A sablon egy központi helyen tárolja az egységes stílusokat, így a módosítások a kártyákon, gombokon, diagramokon, adattáblákban és elemleírásokban is érvényesülnek.

A központosított stílus elkerüli a nem illő színeket, az összeszedhetetlen betűtípusokat és a elrendezési különbségeket, amelyek akkor előfordulhatnak, ha minden komponenst külön stílusban alakítanak ki.

Sztringek formázása

Definiáljuk a formázást egyszer eredményoszloponként. A sablon képes újrahasznosítani a szemantikai modell formátumú stringeket diagramtengelyeken, tooltipekben, adatcímkéken, kártyákon és adatrács cellákon keresztül.

Például egyetlen formátumdefiníció biztosítja, hogy a(z) 1500.5 érték mindig $1,500.50 formában, a(z) 0.25 érték pedig mindig 25% formában jelenjen meg, bárhol is fordulnak elő ezek az értékek.

Böngésző ellenőrzés

Mielőtt közzétennéd az alkalmazást, használd a mellékelt Playwright böngésző-validációs munkafolyamatot, hogy nyisd meg egy valódi böngészőben, és ellenőrizd:

  • A vizuális elemek helyesen jelennek meg.
  • A diagramokat nem vágják le vagy tömörítik.
  • A szöveg olvasható.
  • Az adatrácsok kezelik a túlcsordulást.
  • A betöltés, üres és hiba állapotok használhatók.
  • A szűrők, keresztkiemelés és az adatformázás a várható módon működnek.
  • A böngészőkonzolon nincsenek váratlan hibák.

Ez a munkafolyamat észreveszi a kiépítési és renderelési problémákat, mielőtt a felhasználók észrevennék őket. A böngésző validálása megerősíti a frontend viselkedést. Teszteld külön a telepített csatlakozót egy olyan felhasználóval, aki hozzáfér mind a Fabric alkalmazáshoz, mind a szemantikai modellhez.

Telepítsd és ellenőrizd az alkalmazást

Telepítsd az alkalmazás és a csatlakozó konfigurációját:

npx rayfin up

Nyisd meg a telepített alkalmazást a Fabric portálból. Jelentkezz be, futtatd le minden felhasználói interakciót, és hasonlítsd össze a fontos eredményeket a szemantikai modellel.

Ha egy lekérdezés meghiúsul:

  • Ellenőrizd a munkaterület és a szemantikai modell elemazonosítóit a(z) rayfin.yml elemben.
  • Győződj meg róla, hogy a Semantic Model Execute Queries REST API bérlői beállítása engedélyezve van.
  • Erősítsd meg, hogy a felhasználónak van Build és Read engedélye a szemantikai modellen.
  • Ellenőrizd, hogy a DAX hivatkozik-e meglévő táblákra, oszlopokra és mértékekre.
  • Nézd meg a csatlakozó eredményének hibakategóriáját és üzenetét.
  • Ellenőrizd a böngészőkonzolt kliensoldali hibák után.

Kapcsolódó tartalom

  • Utolsó frissítés időpontja: