Lag en app koblet til en semantisk modell

Bruk dataapp-malen med en Fabric semantisk modellkobling for å bygge en analytisk Fabric-app. Malen gir visualisering, formatering, datarutenett og nettleservalideringsmønstre. Koblingen gir typet, delegert tilgang til en semantisk modell gjennom Fabric Apps-klienten.

Rett ut av boksen inkluderer apper laget med malen:

Fabric-autentisering.
Veiledning for generering av DAX (Data Analysis Expressions) av høyere kvalitet.
Bedriftsklare visuelle komponenter designet for analytiske applikasjoner.
Datarutenett, tematisering, formatering og nettleservalideringsmønstre.

Note

For øyeblikket er Rayfin CLI den støttede måten å lage apper på ved å bruke data-app-malen.

Hvorfor bruke dataapp-malen?

Uten disse innebygde funksjonene må en kodeagent løse autentisering, DAX-generering og visualiseringsdesign fra bunnen av i hver økt. Det kan føre til:

Flere feil og ødelagte eller tomme visuelle effekter.
Inkonsekvent oppførsel i diagrammet.
Unødvendige DAX-spørringer under utvikling og kjøring.

Malen gir gjenbrukbare mønstre som forbedrer påliteligheten, gir mer sammenhengende visuelle elementer i tråd med rapporteringspraksis og reduserer spørringsoverhead. Koblingen standardiserer konfigurasjon av semantiske modeller og kjøretidstilgang.

Forutsetninger

Node.js 20 eller senere.
Tilgang til Fabric.
Et Fabric-arbeidsområde hvor du har tillatelser som bidragsyter, medlem eller administrator.
Fabric Apps-arbeidsbelastningen er aktivert i leietakeren din. Se Create your first Fabric app.
Leietakerinnstillingen Semantic Model Model Execute Queries REST API aktivert.
Bygge- og lesetillatelser på en semantisk modell hostet på Fabric- eller Power BI-kapasitet.
Workspace-ID og item-ID for den semantiske modellen.

Opprette appen

Lag et prosjekt fra dataapp-malen:

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

Bytt <app-name> ut og <workspace-name> med navnene på appen din og Fabric-arbeidsområdet. Åpne deretter mappen for det nye prosjektet:

cd <app-name>

Legg til den semantiske modellkontakten

Hvis du ikke kjenner den semantiske modellens element-ID, list opp semantiske modeller i arbeidsområdet:

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

Legg til den semantiske modellen som en kobling:

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

Kommandoen:

Legger til kontakten salesModel til .rayfin/rayfin.yml
Lager sitt skjema under rayfin/connectors/salesModel/.
Skriver ut en versjonsmatchet npm install kommando for kontaktpakkene.

Kjør nøyaktig den installasjonskommandoen som er skrevet ut av CLI-en.

Den genererte konfigurasjonen 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 genererte version verdien.

Koble malen til den semantiske modellen

Malen inneholder analytiske komponenter og agentveiledning som du kan gjenbruke med koblingen. Konfigurer data-tilgangslaget til å opprette og ConnectorsRayfinClient registrere den semantiske modellens kjøretid:

Important

Bruk connector-klienten for spørringer i semantiske modeller. Hvis stillaset inkluderer en annen semantisk modellklient, bytt ut kall til den i stedet for å opprettholde to data-tilgangsstier.

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

Bruk API-URL-en og publiserbar nøkkel fra Fabric Apps-prosjektet ditt. Behold malens eksisterende Fabric-innloggingsflyt.

Send inn DAX gjennom kontakten:

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

Erstatt Sales med en tabell i din semantiske modell. Sjekk den returnerte statusen før du sender kolonner og rader til et visuelt system.

For mer veiledning om tilkoblingskonfigurasjon og sikkerhet, se Connect Fabric Apps to Fabric data.

Bygg appen med en kodeagent

Stillaset inkluderer instruksjoner og ferdigheter for kodingsagenter. Åpne prosjektet i din foretrukne agent, og beskriv målgruppen, spørsmålene, interaksjonene og visualiseringene for appen.

Du kan for eksempel gjøre følgende:

Åpne prosjektet i Visual Studio Code, og åpne deretter GitHub Copilot Chat-panelet.
Åpne en terminal i prosjektet, og kjør copilotderetter .

Bruk denne prompten som et utgangspunkt:

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.

Bruk malfunksjonene

Dataapp-malen inkluderer gjenbrukbare mønstre for analytiske applikasjoner.

Fabric Apps er standard webapplikasjoner, så du kan implementere funksjoner utenfor disse mønstrene. Funksjoner som ikke er inkludert i malen kan kreve mer tilpasset ingeniørarbeid og validering.

Visuelle effekter

Malen inkluderer kryssmarkering og forhåndskonfigurerte primitiver for:

Stolpediagrammer, inkludert vertikale, horisontale, grupperte og stablede oppsett.
Linjediagrammer med valgfrie markører.
Områdekart.
Spredningsdiagrammer.
Pai- og smultringdiagrammer.
Varmekart.
Boblediagrammer.
Fossefallsdiagrammer.
Enkeltverdikort for KPI-utmeldinger.
Lagdelte og sammensatte visuelle elementer, som stolper med dataetiketter og toaksede linjediagrammer.

Bruk felt og mål som finnes i den sammenhengende semantiske modellen. Ikke bytt ut en mislykket koblingsforespørsel med mock-data.

Du kan be kodeagenten din lage andre visuelle elementer. Visuelle elementer uten en malprimitiv kan kreve flere iterasjoner og validering.

Datanett-funksjonalitet

Malen inkluderer et datarutenett med disse forhåndskonfigurerte mulighetene:

Kolonneoverskrifter hentet fra metadata fra semantiske modeller.
Tall- og datoformatering brukes per kolonne gjennom formatstrenger.
Sortering.
Rullbare rader med overløpshåndtering.
Støtte for lys og mørk tema.
Egendefinerte celle-renderere for:
- Databarer for numeriske verdier.
- Boolske indikatorer.
- Klikkbare URL-er.
- Bildeceller med et lysboks-overlegg.
- Flerfeltceller, som et navn og en rolle i én kolonne.

Du kan legge til andre datagrid-funksjoner, men de kan kreve mer tilpasset ingeniørarbeid.

Tilpasning av tema

Gi kodeagenten din merkevare- eller stylingkrav, som fargepalett, hjørnestil eller font. Malen holder delte stiler samlet på ett sentralt sted, slik at flyten endres til kort, knapper, diagrammer, datarutenett og verktøytips.

Sentralisert styling unngår ujevne farger, inkonsistente skrifttyper og layoutforskjeller som kan oppstå når hver komponent styles separat.

formatstrenger

Definer formatering én gang per resultatkolonne. Malen kan gjenbruke semantiske modellformater på tvers av diagramakser, verktøytips, dataetiketter, kort og datagridceller.

For eksempel vises 1500.5 en enkelt formatdefinisjon som $1,500.50 og 0.25 vises der 25% disse verdiene forekommer.

Nettleservalidering

Før du publiserer appen, bruk den medfølgende Playwright-nettleservalideringsarbeidsflyten for å åpne den i en ekte nettleser og sjekke:

Grafikken gjengives korrekt.
Diagrammer kuttes ikke av eller komprimeres.
Teksten er lesbar.
Datarutenett håndterer overløp.
Laste-, tom- og feiltilstander er brukbare.
Filtre, kryssmarkering og dataformatering fungerer som forventet.
Nettleserkonsollen har ingen uventede feil.

Denne arbeidsflyten fanger opp layout- og renderingsproblemer før brukerne ser dem. Nettleservalidering bekrefter frontend-oppførselen. Test den distribuerte kontakten separat med en bruker som har tilgang til både Fabric-appen og den semantiske modellen.

Distribuer og verifiser appen

Distribuer appens og tilkoblingskonfigurasjonen:

npx rayfin up

Åpne den distribuerte appen fra Fabric-portalen. Logg inn, kjør hver brukerinteraksjon, og sammenlign viktige resultater med den semantiske modellen.

Hvis en spørring feiler:

Bekreft arbeidsområdets og semantiske modell-objekt-IDene i rayfin.yml.
Bekreft at Semantic Model Execute Queries REST API-leietakerinnstillingen er aktivert.
Bekreft at brukeren har Bygg- og Lesetillatelser på den semantiske modellen.
Verifiser at DAX refererer til eksisterende tabeller, kolonner og mål.
Sjekk feilkategorien og meldingen i koblingsresultatet.
Sjekk nettleserkonsollen for feil på klientsiden.

Tilbakemeldinger

Var denne siden nyttig?

Sist oppdatert 2026-09-29