Erstellen einer App, die mit einem semantischen Modell verbunden ist

Verwenden Sie die Daten-App-Vorlage mit einem Fabric-Semantic Model Connector, um eine analytische Fabric-App zu erstellen. Die Vorlage bietet Visualisierung, Formatierung, Datenraster und Browser-Validierungsmuster. Der Connector bietet typisierten, delegierten Zugriff auf ein semantisches Modell über den Fabric Apps Client.

Standardmäßig enthalten mit der Vorlage erstellte Apps:

• Fabric-Authentifizierung.
• Anleitung für die Generierung hochwertigerer DAX-Ausdrücke (Data Analysis Expressions)
• Visuelle Komponenten für analytische Anwendungen, entwickelt für den Unternehmenseinsatz.
• Datenraster, Theming, Formatierung und Browser-Validierungsmuster.

Hinweis

Derzeit wird die Rayfin-CLI unterstützt, um Apps mit der Daten-App-Vorlage zu erstellen.

Warum sollte die Daten-App-Vorlage verwendet werden?

Ohne diese eingebauten Funktionen muss ein Coding-Agent Authentifizierung, DAX-Erstellung und Visualisierungsdesign in jeder Sitzung von Grund auf lösen. Das kann dazu führen:

• Mehr Fehlschläge und kaputtes oder leeres Bild.
• Inkonsistentes Diagrammverhalten.
• Unnötige DAX-Abfragen während Entwicklung und Laufzeit.

Die Vorlage bietet wiederverwendbare Muster, die die Zuverlässigkeit verbessern, kohärentere Visualisierungen liefern, die den Best Practices der Berichterstattung entsprechen, und den Query-Overhead reduzieren. Der Connector standardisiert die Konfiguration semantischer Modelle und den Laufzeitzugriff.

Voraussetzungen

• Node.js 20 oder später.
• Zugriff auf Fabric.
• Ein Fabric Arbeitsbereich, in dem Sie über Berechtigungen "Mitwirkender", "Mitglied" oder "Administrator" verfügen.
• Die in Ihrem Mandanten aktivierte Fabric-App-Workload. Siehe Create your first Fabric App.
• Die Mandanteneinstellung für die REST-API „Abfragen ausführen“ des semantischen Modells ist aktiviert.
• Build- und Read-Berechtigungen auf einem semantischen Modell, das auf Fabric- oder Power BI-Kapazität gehostet wird.
• Die Arbeitsbereichs-ID und die Item-ID für das semantische Modell.

Erstellen der App

Erstellen Sie ein Projekt aus der Daten-App-Vorlage:

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

Ersetze <workspace-name> und <app-name> durch die Namen deiner App und deines Fabric-Arbeitsbereichs. Dann öffne den Ordner für das neue Projekt:

cd <app-name>

Füge den semantischen Modell-Konnektor hinzu

Wenn Sie die ID des semantischen Modells nicht kennen, listen Sie semantische Modelle im Arbeitsbereich auf:

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

Füge das semantische Modell als Verbindungselement hinzu:

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

Der Befehl:

• Fügt den salesModel Anschluss zu rayfin/rayfin.yml hinzu.
• Erzeugt sein Schema unter rayfin/connectors/salesModel/.
• Druckt einen versionsangepassten npm install Befehl für die Connector-Pakete.

Führe genau den Installationsbefehl aus, der von der CLI ausgedruckt wird.

Die erzeugte Konfiguration ähnelt folgendem Beispiel:

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

Behalten Sie den generierten version Wert.

Verbinde die Vorlage mit dem semantischen Modell

Die Vorlage enthält analytische Komponenten und Agentenanleitungen, die Sie mit dem Connector wiederverwenden können. Konfigurieren Sie ihre Datenzugriffsschicht so, dass sie ein ConnectorsRayfinClient erstellt, und registrieren Sie die Laufzeit des semantischen Modells:

Important

Verwenden Sie den Connector-Client für semantische Modellabfragen. Wenn das Gerüst einen weiteren semantischen Modellclient enthält, ersetzen Sie Aufrufe zu ihm, anstatt zwei Datenzugriffspfade zu verwalten.

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

Verwenden Sie die API-URL und den publizierbaren Schlüssel aus Ihrem Fabric Apps-Projekt. Behalte den bestehenden Fabric-Anmeldefluss der Vorlage bei.

DAX über den Konnektor übermitteln:

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

Ersetzen Sie Sales durch eine Tabelle in Ihrem semantischen Modell. Überprüfen Sie den zurückgegebenen Status, bevor Sie Spalten und Zeilen an eine Visualisierung übergeben.

Weitere Hinweise zur Connector-Konfiguration und Sicherheit finden Sie unter Connect Fabric Apps to Fabric Data.

Baue die App mit einem Coding-Agenten

Das Gerüst enthält Anweisungen und Fähigkeiten für Programmierer. Öffnen Sie das Projekt bei Ihrem bevorzugten Agenten und beschreiben Sie die Zielgruppe, Fragen, Interaktionen und Visualisierungen für die App.

Du hast beispielsweise folgende Möglichkeiten:

• Öffne das Projekt in Visual Studio Code und dann den GitHub Copilot Chat-Bereich.
• Öffne ein Terminal im Projektverzeichnis und führe dann copilot aus.

Nutzen Sie diesen Prompt als Ausgangspunkt:

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.

Nutzen Sie die Template-Funktionen

Die Daten-App-Vorlage enthält wiederverwendbare Muster für analytische Anwendungen.

Fabric Apps sind Standard-Webanwendungen, sodass man Funktionen außerhalb dieser Muster implementieren kann. Funktionen, die nicht in der Vorlage enthalten sind, erfordern möglicherweise mehr individuelle Entwicklung und Validierung.

Visuelle Elemente

Die Vorlage enthält Cross-Highlighting und vorkonfigurierte Primitive für:

• Balkendiagramme, einschließlich vertikaler, horizontaler, gruppierter und gestapelter Layouts.
• Liniendiagramme mit optionalen Markern.
• Flächenkarten.
• Streudiagramme.
• Kuchen- und Donutdiagramme.
• Heatmaps.
• Blasendiagramme.
• Wasserfall-Diagramme.
• Einzelwert-Karten für KPI-Hervorhebungen.
• Mehrschichtige und zusammengesetzte Visualisierungen, wie Balken mit Datenbeschriftungen und Liniendiagramme mit zwei Achsen.

Verwenden Sie Felder und Maße, die im zusammenhängenden semantischen Modell existieren. Ersetzen Sie eine fehlgeschlagene Connector-Abfrage nicht durch Mock-Daten.

Du kannst deinen Codierer bitten, andere visuelle Elemente zu erstellen. Visuelle Elemente ohne Vorlagenprimitiv erfordern möglicherweise weitere Iterationen und Validierung.

Datengitterfunktionen

Die Vorlage enthält ein Datengitter mit diesen vorkonfigurierten Funktionen:

• Spaltenüberschriften, abgeleitet aus metadaten semantischen Modells.
• Zahlen- und Datumsformatierung wird pro Spalte über Formatzeichenketten angewendet.
• Sortieren.
• Scrollbare Zeilen mit Overflow-Handling.
• Unterstützung für Licht- und Dunkelthemen.
• Benutzerdefinierte Zellrenderer für:
  • Datenbalken für numerische Werte.
  • Boolesche Indikatoren.
  • Anklickbare URLs.
  • Bildzellen mit einem Lightbox-Overlay.
  • Zellen mit mehreren Feldern, etwa Name und Rolle in einer Spalte.

Du kannst weitere Datengitter-Funktionen hinzufügen, aber die erfordern möglicherweise mehr individuelle Entwicklung.

Designmanagement

Geben Sie Ihrem Coding-Agenten Branding- oder Stylinganforderungen an, wie eine Farbpalette, einen Eckstil oder eine Schriftart. Die Vorlage hält gemeinsame Stile an zentraler Stelle vor, sodass Änderungen an Karten, Buttons, Diagramme, Datenraster und Tooltips weitergegeben werden.

Zentralisiertes Styling vermeidet unpassende Farben, inkonsistente Schriftarten und Layoutunterschiede, die auftreten können, wenn jede Komponente separat gestaltet wird.

Formatzeichenfolgen

Definiere die Formatierung einmal pro Ergebnisspalte. Die Vorlage kann semantische Modellformat-Strings über Diagrammachsen, Tooltips, Datenlabels, Karten und Datengitterzellen hinweg wiederverwenden.

Zum Beispiel sorgt eine einzelne Formatdefinition dafür, dass 1500.5 überall dort, wo diese Werte vorkommen, als $1,500.50 und 0.25 als 25% angezeigt wird.

Browservalidierung

Bevor Sie die App veröffentlichen, verwenden Sie den mitgelieferten Playwright-Browser-Validierungs-Workflow, um sie in einem echten Browser zu öffnen und zu überprüfen:

• Die visuellen Elemente werden korrekt dargestellt.
• Diagramme werden nicht abgeschnitten oder komprimiert.
• Der Text ist lesbar.
• Datengitter gehen mit Überlauf um.
• Lade-, leer- und Fehlerzustände sind nutzbar.
• Filter, Kreuzhervorhebung und Datenformatierung funktionieren wie erwartet.
• Die Browser-Konsole zeigt keine unerwarteten Fehler.

Dieser Workflow erkennt Layout- und Rendering-Probleme, bevor Nutzer sie sehen. Die Browser-Validierung bestätigt das Frontend-Verhalten. Testen Sie den bereitgestellten Connector separat mit einem Nutzer, der sowohl auf die Fabric-App als auch auf das semantische Modell Zugriff hat.

Deploye und verifiziere die App

Bereite die App- und Connector-Konfiguration aus:

npx rayfin up

Öffnen Sie die bereitgestellte App über das Fabric-Portal. Melden Sie sich an, führen Sie jede Benutzerinteraktion aus und vergleichen Sie wichtige Ergebnisse mit dem semantischen Modell.

Wenn eine Abfrage fehlschlägt:

• Bestätigen Sie die IDs des Arbeitsbereichs und des Elements des semantischen Modells in rayfin.yml.
• Bestätigen Sie, dass die REST-API-Mandanteinstellung Semantic Model Execute Queries aktiviert ist.
• Bestätigen Sie, dass der Benutzer Build- und Read-Rechte im semantischen Modell hat.
• Überprüfen Sie, dass der DAX bestehende Tabellen, Spalten und Maße referenziert.
• Überprüfen Sie die Fehlerkategorie und die Meldung des Connector-Ergebnisses.
• Überprüfen Sie die Browser-Konsole auf clientseitige Fehler.

Verwandte Inhalte

• Verbinden Sie Fabric-Apps mit Fabric-Daten
• Erstellen Sie eine semantische Modell-App mit GitHub Copilot
• Authentifizierung für Fabric-Apps
• Eine Fabric-App in Fabric bereitstellen