Opret en app forbundet til en semantisk model

Brug dataapp-skabelonen med en Fabric semantisk model-connector til at bygge en analytisk Fabric-app. Skabelonen giver visualisering, formatering, datagrid og browservalideringsmønstre. Connectoren giver typet, delegeret adgang til en semantisk model gennem Fabric Apps-klienten.

Ud af boksen inkluderer apps, der er lavet med skabelonen:

Fabric-autentificering.
Vejledning til generering af DAX (Data Analysis Expressions) af højere kvalitet.
Virksomhedsklare visuelle komponenter designet til analytiske anvendelser.
Datagitter, tematisering, formatering og browservalideringsmønstre.

Bemærkning

I øjeblikket er Rayfin CLI den understøttede måde at oprette apps på ved at bruge dataapp-skabelonen.

Hvorfor bruge data-app-skabelonen?

Uden disse indbyggede funktioner skal en kodningsagent løse autentificering, DAX-generering og visualiseringsdesign fra bunden i hver session. Det kan føre til:

Flere fejl og ødelagte eller tomme visuelle effekter.
Inkonsekvent adfærd i diagrammet.
Unødvendige DAX-forespørgsler under udvikling og kørsel.

Skabelonen giver genanvendelige mønstre, der forbedrer pålideligheden, giver mere sammenhængende visuelle elementer i overensstemmelse med rapporteringspraksis og reducerer forespørgselsomkostninger. Connectoren standardiserer konfiguration af semantiske modeller og runtime-adgang.

Forudsætninger

Node.js 20 eller senere.
Adgang til Fabric.
Et Fabric-arbejdsområde, hvor du har tilladelser til bidragsyger, medlem eller administrator.
Fabric Apps-arbejdsbelastningen er aktiveret i din lejer. Se Create your first Fabric app.
Lejerindstillingen Semantic Model Execute Queries REST API-lejeren er aktiveret.
Bygge- og læsetilladelser på en semantisk model, der hostes på Fabric- eller Power BI-kapacitet.
Arbejdsområde-ID og objekt-ID for den semantiske model.

Opret appen

Opret et projekt ud fra dataapp-skabelonen:

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

Erstat <app-name> og <workspace-name> med navnene på din app og Fabric workspace. Åbn derefter mappen med det nye projekt:

cd <app-name>

Tilføj den semantiske model-connector

Hvis du ikke kender det semantiske model-item-ID, så list semantiske modeller i arbejdsområdet:

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

Tilføj den semantiske model som en forbindelse:

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

Kommandoen:

Tilføjer stikket salesModel til .rayfin/rayfin.yml
Opretter sit skema under rayfin/connectors/salesModel/.
Udskriver en versionsmatchet npm install kommando til stikpakkerne.

Kør den præcise installationskommando, som CLI'en printer.

Den genererede konfiguration ligner følgende eksempel:

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

Behold den genererede version værdi.

Forbind skabelonen til den semantiske model

Skabelonen indeholder analytiske komponenter og agentvejledning, som du kan genbruge med connectoren. Konfigurér dens dataadgangslag til at oprette og ConnectorsRayfinClient registrere den semantiske model-runtime:

Important

Brug connector-klienten til forespørgsler i semantiske modeller. Hvis stilladset inkluderer en anden semantisk modelklient, skal kald til den erstattes i stedet for at vedligeholde to dataadgangsstier.

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

Brug API-URL'en og den publicerbare nøgle fra dit Fabric Apps-projekt. Behold skabelonens eksisterende Fabric-loginflow.

Indsend DAX gennem stikket:

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

Erstat Sales med en tabel i din semantiske model. Tjek den returnerede status, før du sender kolonner og rækker til en visuel maskine.

For mere vejledning om connectorkonfiguration og sikkerhed, se Connect Fabric Apps to Fabric data.

Byg appen med en kodningsagent

Stilladset indeholder instruktioner og færdigheder til kodningsagenter. Åbn projektet i din foretrukne agent, og beskriv målgruppen, spørgsmålene, interaktionerne og visualiseringerne til appen.

Du kan for eksempel:

Åbn projektet i Visual Studio Code, og åbn derefter GitHub Copilot Chat-panelet.
Åbn en terminal i projektet, og kør copilotderefter .

Brug denne prompt som udgangspunkt:

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.

Brug skabelonens funktioner

Dataapp-skabelonen indeholder genanvendelige mønstre til analytiske applikationer.

Fabric Apps er standard webapplikationer, så du kan implementere funktioner uden for disse mønstre. Funktioner, der ikke er inkluderet i skabelonen, kan kræve mere skræddersyet ingeniørarbejde og validering.

Visuelle elementer

Skabelonen inkluderer krydsfremhævelse og forudkonfigurerede primitiver til:

Søjlediagrammer, inklusive vertikale, horisontale, grupperede og stablede layouts.
Linjediagrammer med valgfrie markører.
Arealkort.
Spredningsdiagrammer.
Pie- og donutdiagrammer.
Heatmaps.
Boblediagrammer.
Vandfaldsdiagrammer.
Enkeltværdikort til KPI-udmeldinger.
Lagdelte og sammensatte visualiseringer, såsom bjælker med dataetiketter og to-akse linjediagrammer.

Brug felter og mål, der findes i den sammenhængende semantiske model. Erstat ikke en fejlet connector-forespørgsel med mock-data.

Du kan bede din kodningsagent om at generere andre visuelle elementer. Visuelle elementer uden en skabelonprimitiv kan kræve flere iterationer og validering.

Datagitterkapaciteter

Skabelonen indeholder et datagrid med disse forudkonfigurerede funktioner:

Kolonneoverskrifter afledt af metadata fra semantiske modeller.
Nummer- og datoformatering anvendes pr. kolonne gennem formatstrenge.
Sortering.
Scrollbare rækker med overflow-håndtering.
Støtte til lys og mørke temaer.
Brugerdefinerede cellerenderere til:
- Databjælker for numeriske værdier.
- Booleske indikatorer.
- Klikbare URL'er.
- Billedceller med et lysboks-overlay.
- Multifelt-celler, såsom navn og rolle i én kolonne.

Du kan tilføje andre datagrid-funktioner, men de kan kræve mere specialudviklet design.

Temaer

Giv din kodningsagent branding- eller stylingkrav, såsom farvepalet, hjørnestil eller skrifttype. Skabelonen holder delte stilarter samlet ét centralt sted, så flowet ændres til kort, knapper, diagrammer, datagitre og tooltips.

Centraliseret styling undgår ulige farver, inkonsistente skrifttyper og layoutforskelle, der kan opstå, når hver komponent styles separat.

Formatstrenge

Definér formatering én gang pr. resultatkolonne. Skabelonen kan genbruge semantiske modelformatstrenge på tværs af diagramakser, tooltips, dataetiketter, kort og datagridceller.

For eksempel viser 1500.5 en enkelt formatdefinition sig som $1,500.50 og 0.25 vises som 25% hvor disse værdier optræder.

Browservalidering

Før du udgiver appen, brug den medfølgende Playwright-browservalideringsproces til at åbne den i en rigtig browser og tjek:

Visuals gengives korrekt.
Diagrammer bliver ikke klippet af eller komprimeret.
Teksten er læsbar.
Datagitter håndterer overflow.
Indlæsnings-, tom- og fejltilstande er brugbare.
Filtre, krydsfremhævelse og dataformatering fungerer som forventet.
Browserkonsollen har ingen uventede fejl.

Denne arbejdsgang fanger layout- og renderingsproblemer, før brugerne ser dem. Browservalidering bekræfter frontend-adfærden. Test den deployerede connector separat med en bruger, der har adgang til både Fabric-appen og den semantiske model.

Udrul og verificér appen

Udrul appen og connector-konfigurationen:

npx rayfin up

Åbn den deployerede app fra Fabric-portalen. Log ind, kør hver brugerinteraktion, og sammenlign vigtige resultater med den semantiske model.

Hvis en forespørgsel fejler:

Bekræft arbejdsområdets og den semantiske model-item IDs i rayfin.yml.
Bekræft, at Lejerindstillingen Semantic Model Execute Queries REST API er aktiveret.
Bekræft, at brugeren har Build and Read-rettigheder på den semantiske model.
Kontroller, at DAX refererer til eksisterende tabeller, kolonner og målinger.
Tjek fejlkategorien og beskeden for stikresultatet.
Tjek browserkonsollen for fejl på klientsiden.

Feedback

Var denne side nyttig?

Sidst opdateret den 2026-09-29