Skapa en app som är ansluten till en semantisk modell

Använd dataapp-mallen med en Fabric semantisk modellkoppling för att bygga en analytisk Fabric-app. Mallen tillhandahåller visualisering, formatering, datarutnät och webbläsarvalideringsmönster. Kopplingen ger typad, delegerad åtkomst till en semantisk modell via Fabric Apps-klienten.

Appar som skapats med mallen är:

Fabric-autentisering.
Vägledning för generering av DAX (Data Analysis Expressions) av högre kvalitet.
Företagsklara visuella komponenter designade för analytiska tillämpningar.
Datanät, tematisering, formatering och webbläsarvalideringsmönster.

Note

För närvarande stöds Rayfin CLI för att skapa appar genom att använda dataappsmallen.

Varför ska du använda dataappmallen?

Utan dessa inbyggda funktioner måste en kodagent lösa autentisering, DAX-generering och visualiseringsdesign från grunden i varje session. Det kan leda till:

Fler misslyckanden och trasiga eller tomma visuella effekter.
Inkonsekvent diagrambeteende.
Onödiga DAX-frågor under utveckling och körning.

Mallen erbjuder återanvändbara mönster som förbättrar tillförlitligheten, ger mer sammanhängande visuella effekter i linje med rapporteringspraxis och minskar frågeöverhead. Connectorn standardiserar konfiguration av semantiska modeller och åtkomst under körtid.

Förutsättningar

Node.js 20 eller senare.
Åtkomst till Fabric.
En Fabric arbetsyta där du har behörighet som deltagare, medlem eller administratör.
Arbetsbelastningen Fabric Apps aktiverad i din klientorganisation. Se Skapa din första Fabric-app.
Tenantinställningen för REST API:t Execute Queries i Semantic Model är aktiverad.
Bygg- och läsbehörigheter på en semantisk modell som är värd på Fabric- eller Power BI-kapacitet.
Workspace-ID och objekt-ID för den semantiska modellen.

Skapa appen

Skapa ett projekt från dataappsmallen:

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

Byt ut <app-name> och <workspace-name> med namnen på din app och Fabric workspace. Öppna sedan mappen för nya projekt:

cd <app-name>

Lägg till den semantiska modellkontakten

Om du inte känner till det semantiska modellens item-ID, lista semantiska modeller i arbetsytan:

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

Lägg till den semantiska modellen som en koppling:

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

Kommandot:

Lägger till kontakten salesModel till rayfin/rayfin.yml.
Skapar sitt schema under rayfin/connectors/salesModel/.
Skriver ut ett versionsmatchat npm install kommando för kontaktpaketen.

Kör exakt det installationskommando som CLI:n skriver ut.

Den genererade konfigurationen liknar följande exempel:

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

Behåll det genererade version värdet.

Koppla mallen till den semantiska modellen

Mallen innehåller analytiska komponenter och agentvägledning som du kan återanvända med kopplingen. Konfigurera dataåtkomstlagret så att det skapar en ConnectorsRayfinClient och registrerar körningstiden för den semantiska modellen:

Important

Använd connector-klienten för frågor om semantiska modeller. Om stommen innehåller en annan klient för den semantiska modellen ska du ersätta anropen till den i stället för att upprätthålla två åtkomstvägar till data.

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

Använd API-URL:en och publicierbar nyckel från ditt Fabric Apps-projekt. Behåll mallens befintliga Fabric-inloggningsflöde.

Skicka in DAX via kopplingen:

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

Ersätt Sales med en tabell i din semantiska modell. Kontrollera den returnerade statusen innan du skickar kolumner och rader till en visuell enhet.

För mer vägledning om anslutningskonfiguration och säkerhet, se Connect Fabric Apps to Fabric-data.

Bygg appen med en kodagent

Mallen innehåller instruktioner och färdigheter för kodningsagenter. Öppna projektet i din föredragna agent och beskriv målgruppen, frågor, interaktioner och visualiseringar för appen.

Till exempel kan du:

Öppna projektet i Visual Studio Code och öppna sedan GitHub Copilot Chat-panelen.
Öppna en terminal i projektet och kör sedan copilot.

Använd denna prompt som utgångspunkt:

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.

Använd mallfunktionerna

Dataappmallen innehåller återanvändbara mönster för analytiska applikationer.

Fabric Apps är standardwebbapplikationer, så du kan implementera funktioner utanför dessa mönster. Funktioner som inte ingår i mallen kan kräva mer anpassad ingenjörskonst och validering.

Bildmaterial

Mallen inkluderar korsmarkering och förkonfigurerade primitiver för:

Stapeldiagram, inklusive vertikala, horisontella, grupperade och staplade layouter.
Linjediagram med valfria markörer.
Områdeskartor.
Spridningsdiagram.
Paj- och munkdiagram.
Värmekartor.
Bubbeldiagram.
Vattenfallsdiagram.
Kort med ett enda värde för KPI-framhävningar.
Skiktade och sammansatta visualiseringar, som staplar med dataetiketter och linjediagram med två axlar.

Använd fält och mått som finns i den sammanhängande semantiska modellen. Byt inte ut en misslyckad kopplingsfråga med mockdata.

Du kan be din kodagent att generera andra visuella inslag. Visuella delar utan mall-primitiv kan kräva fler iterationer och validering.

Funktioner för datarutnät

Mallen inkluderar ett datanät med dessa förkonfigurerade funktioner:

Kolumnrubriker härledda från metadata för semantiska modeller.
Nummer- och datumformatering appliceras per kolumn genom formatsträngar.
Sortering.
Rullbara rader med överflödeshantering.
Stöd för ljusa och mörka tema.
Anpassade cellrenderare för:
- Datafält för numeriska värden.
- Booleska indikatorer.
- Klickbara URL:er.
- Bildceller med en lightbox-överlagring.
- Flerfältsceller, såsom namn och roll i en kolumn.

Du kan lägga till andra datagrid-funktioner, men de kan kräva mer anpassad design.

Tematisering

Ge din kodningsagent varumärkes- eller stylingkrav, såsom färgpalett, hörnstil eller typsnitt. Mallen samlar gemensamma stilar på ett centralt ställe så att ändringar slår igenom i kortkomponenter, knappar, diagram, datagridar och verktygstips.

Centraliserad styling undviker ommatchade färger, inkonsekventa typsnitt och layoutskillnader som kan uppstå när varje komponent stylas separat.

Formatera strängar

Definiera formatering en gång per resultatkolumn. Mallen kan återanvända semantiska modellformatsträngar över diagramaxlar, verktygstips, dataetiketter, kort och dataruttceller.

Till exempel gör en enda formatdefinition att 1500.5 visas som $1,500.50 och att 0.25 visas som 25% överallt där dessa värden förekommer.

Webbläsarvalidering

Innan du publicerar appen, använd det medföljande arbetsflödet för Playwright-webbläsarvalidering för att öppna den i en riktig webbläsare och kontrollera:

De visuella elementen återges korrekt.
Diagram är inte avskurna eller komprimerade.
Texten är läsbar.
Datanät hanterar överflöd.
Laddnings-, tom- och feltillstånd är användbara.
Filter, korsmarkering och dataformatering fungerar som förväntat.
Webbläsarkonsolen har inga oväntade fel.

Detta arbetsflöde fångar layout- och renderingsproblem innan användarna ser dem. Webbläsarvalidering bekräftar frontend-beteendet. Testa den distribuerade anslutningsappen separat med en användare som har åtkomst till både Fabric-appen och den semantiska modellen.

Distribuera och verifiera appen

Distribuera appen och anslutningskonfigurationen:

npx rayfin up

Öppna den distribuerade appen från Fabric-portalen. Logga in, kör varje användarinteraktion och jämför viktiga resultat med den semantiska modellen.

Om en fråga misslyckas:

Bekräfta arbetsytans och den semantiska modellens objekt-ID i rayfin.yml.
Kontrollera att klientorganisationsinställningen för Semantic Model Execute Queries REST API är aktiverad.
Bekräfta att användaren har bygg- och läsbehörigheter på den semantiska modellen.
Verifiera att DAX refererar till befintliga tabeller, kolumner och mått.
Kontrollera anslutningsresultatets felkategori och felmeddelande.
Kolla webbläsarkonsolen för klientfel.

Feedback

Var den här sidan till hjälp?

Uppdaterades senast 2026-09-29