Een app maken die is verbonden met een semantisch model

Gebruik de data-app template met een Fabric semantic model connector om een analytische Fabric-app te bouwen. Het sjabloon biedt visualisatie, opmaak, dataraster en browservalidatiepatronen. De connector biedt getypte, gedelegeerde toegang tot een semantisch model via de Fabric Apps-client.

Apps die met de sjabloon zijn gemaakt, zijn standaard:

  • Fabric-authenticatie.
  • Richtlijnen voor het genereren van DAX (Data Analysis Expressions) van hogere kwaliteit.
  • Bedrijfsklare visuele componenten, ontwikkeld voor analytische toepassingen.
  • Datagrid, thematisering, opmaak en browservalidatiepatronen.

Opmerking

Momenteel is de Rayfin CLI de ondersteunde manier om apps te maken met behulp van de data-app template.

Waarom de sjabloon voor de gegevens-app gebruiken?

Zonder deze ingebouwde mogelijkheden moet een codeeragent authenticatie, DAX-generatie en visualisatieontwerp vanaf nul oplossen in elke sessie. Dat kan leiden tot:

  • Meer storingen en defecte of lege visualisaties.
  • Inconsistent gedrag in de grafiek.
  • Onnodige DAX-queries tijdens ontwikkeling en uitvoering.

De template biedt herbruikbare patronen die de betrouwbaarheid verbeteren, meer samenhangende visuals produceren die aansluiten bij de best practices voor rapportage en de overhead voor query's verminderen. De connector standaardiseert de configuratie van het semantische model en runtime-toegang.

Prerequisites

  • Node.js 20 of hoger.
  • Toegang tot Fabric.
  • Een Fabric werkruimte met inzender-, lid- of beheerdersmachtigingen.
  • De workload Fabric Apps ingeschakeld in uw tenant. Zie Create your first Fabric app.
  • De Semantic Model Execute Query's REST API-tenantinstelling ingeschakeld.
  • Bouw- en leesrechten op een semantisch model dat wordt gehost op Fabric- of Power BI-capaciteit.
  • De werkruimte-ID en item-ID voor het semantische model.

De app maken

Maak een project aan vanuit de data-app sjabloon:

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

Vervang <app-name> en <workspace-name> door de namen voor je app en Fabric-werkruimte. Open dan de map nieuw project:

cd <app-name>

Voeg de semantische modelconnector toe

Als je de item-ID van het semantische model niet weet, vermeld dan semantische modellen in de werkruimte:

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

Voeg het semantische model toe als connector:

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

De opdracht:

  • Voegt de salesModel connector toe aan rayfin/rayfin.yml.
  • Maakt zijn schema aan onder rayfin/connectors/salesModel/.
  • Geeft een bij de versie passend npm install-commando weer voor de connectorpakketten.

Voer exact het installatiecommando uit dat door de CLI is afgedrukt.

De gegenereerde configuratie lijkt op het volgende voorbeeld:

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

Houd de gegenereerde version waarde behouden.

Verbind het sjabloon met het semantische model

De template bevat analytische componenten en agentbegeleiding die je kunt hergebruiken met de connector. Configureer de laag voor gegevenstoegang om een ConnectorsRayfinClient te maken en de runtime van het semantische model te registreren:

Important

Gebruik de connectorclient voor semantische modelzoekopdrachten. Als de scaffold een andere semantische modelclient bevat, vervang dan aanroepen naar deze in plaats van twee data-toegangspaden te onderhouden.

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

Gebruik de API-URL en publiceerbare sleutel van je Fabric Apps-project. Houd de bestaande Fabric-aanmeldflow van het sjabloon aan.

DAX indienen via de connector:

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

Vervang Sales door een tabel in je semantisch model. Controleer de geretourneerde status voordat je kolommen en rijen doorgeeft aan een visual.

Voor meer richtlijnen over connectorconfiguratie en beveiliging, zie Connect Fabric Apps to Fabric data.

Bouw de app met een programmeeragent

De steiger bevat instructies en vaardigheden voor codeeragenten. Open het project in je voorkeursagent en beschrijf de doelgroep, vragen, interacties en visualisaties voor de app.

U kunt bijvoorbeeld het volgende doen:

  • Open het project in Visual Studio Code en open vervolgens het GitHub Copilot Chat-venster.
  • Open een terminal in het project en voer vervolgens copilot uit.

Schermafbeelding van de interface van GitHub Copilot Chat in Visual Studio Code.

Gebruik deze prompt als uitgangspunt:

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.

Gebruik de template-mogelijkheden

De sjabloon voor data-apps bevat herbruikbare patronen voor analytische toepassingen.

Fabric Apps zijn standaard webapplicaties, dus je kunt functies buiten deze patronen implementeren. Functies die niet in de template staan, kunnen meer maatwerk en validatie vereisen.

Visuele elementen

De template bevat kruismarkering en vooraf geconfigureerde primitieven voor:

  • Staafdiagrammen met verticale, horizontale, gegroepeerde en gestapelde indelingen.
  • Lijnkaarten met optionele markers.
  • Oppervlaktekaarten.
  • Scatterdiagrammen.
  • Taart- en donutdiagrammen.
  • Heatmaps.
  • Bubbelgrafieken.
  • Watervalgrafieken.
  • Kaarten met één waarde voor KPI-oproepen.
  • Gelaagde en samengestelde visuals, zoals balken met datalabels en dubbelassige lijndiagrammen.

Gebruik velden en maten die bestaan in het verbonden semantische model. Vervang een mislukte connectorquery niet door mockdata.

Je kunt je programmeeragent vragen om andere visuals te genereren. Visuals zonder een sjabloonprimitieve kunnen meer iteraties en validatie vereisen.

Mogelijkheden voor gegevensraster

De template bevat een datagrid met deze vooraf geconfigureerde mogelijkheden:

  • Kolomkoppen afgeleid van metadata van semantisch model.
  • Nummer- en datumopmaak wordt per kolom toegepast via formaatstrings.
  • Sorteren.
  • Scrollbare rijen met overloopafhandeling.
  • Ondersteuning van het lichte en donkere thema.
  • Aangepaste celrenderers voor:
    • Databalken voor numerieke waarden.
    • Booleaanse indicatoren.
    • Klikbare URL's.
    • Beeldcellen met een lightbox-overlay.
    • Cellen met meerdere velden, zoals een naam en rol in één kolom.

Je kunt andere datagrid-mogelijkheden toevoegen, maar die vereisen mogelijk meer maatwerk.

Thematisering

Geef je codeeragent branding- of stylingvereisten, zoals een kleurenpalet, hoekstijl of lettertype. De template houdt gedeelde stijlen op één centrale locatie, zodat de flow verandert naar kaarten, knoppen, grafieken, datagrids en tooltips.

Gecentraliseerde styling voorkomt mismatched kleuren, inconsistente lettertypen en lay-outverschillen die kunnen optreden wanneer elk component afzonderlijk wordt gestyled.

Opmaak van tekenreeksen

Definieer de opmaak eenmaal per resultaatkolom. Het sjabloon kan opmaaktekenreeksen van het semantische model hergebruiken voor grafiekassen, tooltips, gegevenslabels, kaarten en cellen in gegevensrasters.

Bijvoorbeeld, een enkele formatdefinitie blijft 1500.5 weergegeven als $1,500.50 en 0.25 weergegeven als 25% waar die waarden voorkomen.

Browservalidatie

Voordat je de app publiceert, gebruik je de meegeleverde Playwright-browservalidatieworkflow om deze in een echte browser te openen en te controleren:

  • Beelden worden correct weergegeven.
  • Grafieken worden niet afgeknipt of samengedrukt.
  • De tekst is leesbaar.
  • Datarasters gaan om met overloop.
  • Laad-, leeg- en fouttoestanden zijn bruikbaar.
  • Filters, cross-highlight en dataformatting werken zoals verwacht.
  • De browserconsole vertoont geen onverwachte fouten.

Deze workflow ontdekt layout- en renderingproblemen voordat gebruikers ze zien. Browservalidatie bevestigt het frontend-gedrag. Test de geïmplementeerde connector apart met een gebruiker die toegang heeft tot zowel de Fabric-app als het semantische model.

Implementeer en controleer de app

Rol de app en connectorconfiguratie uit:

npx rayfin up

Open de uitgerolde app via het Fabric-portaal. Log in, voer elke gebruikersinteractie uit en vergelijk belangrijke resultaten met het semantische model.

Als een query faalt:

  • Bevestig de item-id's van de werkruimte en het semantisch model in rayfin.yml.
  • Bevestig dat de tenantinstelling Semantic Model Execute Queries REST API is ingeschakeld.
  • Bevestig dat de gebruiker Build- en Read-rechten heeft op het semantische model.
  • Controleer of de DAX verwijst naar bestaande tabellen, kolommen en metingen.
  • Controleer de foutcategorie en het bericht van het connectorresultaat.
  • Controleer de browserconsole op client-side fouten.

Verwante inhoud

  • Laatst bijgewerkt om