Creare un'app connessa a un modello semantico

Usa il modello di app dati con un connettore per modelli semantici di Fabric per creare un'app analitica di Fabric. Il modello fornisce visualizzazione, formattazione, griglia dati e pattern di validazione del browser. Il connettore fornisce accesso tipizzato e delegato a un modello semantico tramite il client Fabric Apps.

Le app create con il modello includono:

Autenticazione Fabric.
Linee guida per la generazione di espressioni DAX (Data Analysis Expressions) di qualità superiore.
Componenti visivi pronti per l'impresa progettati per applicazioni analitiche.
Griglia dati, temi, formattazione e pattern di convalida del browser.

Note

Attualmente, la CLI Rayfin è il modo supportato per creare app utilizzando il template data app.

Perché usare il modello di app dati?

Senza queste capacità integrate, un agente di codifica deve risolvere da zero autenticazione, generazione DAX e progettazione di visualizzazione in ogni sessione. Questo può portare a:

Altri fallimenti e immagini rotte o vuote.
Comportamento incoerente nei grafici.
Query DAX inutili durante lo sviluppo e l'esecuzione.

Il template fornisce pattern riutilizzabili che migliorano l'affidabilità, producono immagini più coerenti allineate alle migliori pratiche di reportistica e riducono il sovraccarico delle query. Il connettore standardizza la configurazione semantica dei modelli e l'accesso in runtime.

Prerequisiti

Node.js 20 o versione successiva.
Accesso a Fabric.
Area di lavoro Fabric in cui si dispone delle autorizzazioni Collaboratore, Membro o Amministratore.
Il carico di lavoro di Fabric Apps abilitato nel tenant. Vedi Crea la tua prima app Fabric.
Impostazione del tenant dell'API REST Execute Queries (Esegui query) dell'API REST del modello semantico abilitata.
Autorizzazioni di compilazione e lettura su un modello semantico ospitato in una capacità di Fabric o Power BI.
L'ID dello spazio di lavoro e l'ID dell'elemento per il modello semantico.

Creare l'app

Crea un progetto dal modello data app:

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

Sostituisci <app-name> e <workspace-name> con i nomi della tua app e dello spazio di lavoro Fabric. Poi apri la nuova cartella del progetto:

cd <app-name>

Aggiungi il connettore del modello semantico

Se non conosci l'ID dell'elemento semantico del modello, elenca i modelli semantici nello spazio di lavoro:

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

Aggiungi il modello semantico come connettore:

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

Il comando :

Aggiunge il salesModel connettore a rayfin/rayfin.yml.
Crea il suo schema sotto rayfin/connectors/salesModel/.
Stampa un comando npm install con versione corrispondente per i pacchetti del connettore.

Esegui il comando di installazione esatto stampato dalla CLI.

La configurazione generata somiglia al seguente esempio:

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

Conserva il valore generato version .

Collega il template al modello semantico

Il modello contiene componenti analitici e indicazioni per agenti che puoi riutilizzare con il connettore. Configura il livello di accesso ai dati per creare un ConnectorsRayfinClient e registrare il runtime del modello semantico:

Importante

Usa il client del connettore per eseguire query sul modello semantico. Se la struttura include un altro client del modello semantico, sostituisci le chiamate a quest’ultimo anziché mantenere due percorsi di accesso ai dati.

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

Usa l'URL API e la chiave pubblicabile dal tuo progetto Fabric Apps. Mantieni il flusso di accesso Fabric esistente del template.

Invia DAX tramite il connettore:

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

Sostituisci Sales con una tabella nel tuo modello semantico. Controlla lo stato restituito prima di passare colonne e righe a un oggetto visivo.

Per ulteriori indicazioni sulla configurazione dei connettori e sulla sicurezza, vedi Connect Fabric Apps to Fabric data.

Costruisci l'app con un agente di codifica

La struttura include istruzioni e competenze per gli agenti di programmazione. Apri il progetto nel tuo agente preferito e descrivi il pubblico, le domande, le interazioni e le visualizzazioni per l'app.

Ad esempio, puoi:

Apri il progetto in Visual Studio Code, poi apri il pannello GitHub Copilot Chat.
Apri un terminale nel progetto, e poi esegui copilot.

Usa questo prompt come punto di partenza:

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.

Usa le funzionalità del template

Il modello per app di dati include schemi riutilizzabili per applicazioni analitiche.

Le Fabric Apps sono applicazioni web standard, quindi puoi implementare funzionalità al di fuori di questi pattern. Le funzionalità non incluse nel template potrebbero richiedere più ingegneria personalizzata e validazione.

Elementi grafici

Il template include evidenziazioni incrociate e primitive preconfigurate per:

Grafici a barre, inclusi layout verticali, orizzontali, raggruppati e impilati.
Grafici delle linee con marcatori opzionali.
Carte dell'area.
Grafici a dispersione.
Grafici a torta e ciambelle.
Mappe di calore.
Grafici a bolle.
Carte delle cascate.
Schede a valore singolo per le chiamate dei KPI.
Immagini stratificate e composite, come barre con etichette dati e grafici a linee a doppio asse.

Usa campi e misure che esistono nel modello semantico connesso. Non sostituire una query del connettore non riuscita con dati simulati.

Puoi chiedere al tuo agente di codifica di generare altri elementi visivi. Le immagini senza un primitivo template potrebbero richiedere più iterazioni e validazioni.

Funzionalità della griglia dei dati

Il modello include una griglia dati con queste capacità preconfigurate:

Intestazioni di colonna derivate dai metadati dei modelli semantici.
Formattazione numerica e di data applicata per colonna tramite stringhe di formato.
Ordinamento.
Righe scorribili con gestione dell'overflow.
Supporto per i temi di luce e oscurità.
Renderer di celle personalizzati per:
- Barre dei dati per valori numerici.
- Indicatori booleani.
- URL cliccabili.
- Celle immagine con sovrapposizione lightbox.
- Celle con più campi, come nome e ruolo in una colonna.

Puoi aggiungere altre capacità di data grid, ma potrebbero richiedere più ingegneria personalizzata.

Tematizzazione

Indica al tuo agente di codifica i requisiti di branding o stile, come una palette di colori, uno stile di angolo o un carattere. Il template mantiene gli stili condivisi in un'unica posizione centrale, così le modifiche fluiscono su carte, pulsanti, grafici, griglie dati e tooltip.

Uno stile centralizzato evita colori disomogenei, font incoerenti e differenze di layout che possono verificarsi quando ogni componente è stilizzato separatamente.

Stringhe di formato

Definisci la formattazione una volta per ogni colonna del risultato. Il template può riutilizzare stringhe di formato semantico del modello su assi di grafico, tooltip, etichette dati, schede e celle della griglia dati.

Ad esempio, un'unica definizione di formato mantiene 1500.5 visualizzato come $1,500.50 e 0.25 visualizzato come 25% ovunque compaiano tali valori.

Validazione del browser

Prima di pubblicare l'app, usa il flusso di lavoro di validazione del browser Playwright incluso per aprirla in un vero browser e controlla:

La grafica viene visualizzata correttamente.
I grafici non sono tagliati o compressi.
Il testo è leggibile.
Le griglie dati gestiscono il surflow.
Caricamento, vuoto e stati di errore sono utilizzabili.
Filtri, evidenziazioni incrociate e formattazione dei dati funzionano come previsto.
La console del browser non presenta errori inaspettati.

Questo workflow rileva i problemi di layout e rendering prima che gli utenti li vedano. La validazione del browser conferma il comportamento del frontend. Testa separatamente il connettore distribuito con un utente che abbia accesso sia all'app Fabric che al modello semantico.

Distribuisci e verifica l'app

Distribuisci l'app e la configurazione del connettore:

npx rayfin up

Apri l'app distribuita dal portale Fabric. Accedi, esegui ogni interazione utente e confronta i risultati importanti con il modello semantico.

Se una query fallisce:

Conferma gli ID degli elementi dello spazio di lavoro e del modello semantico in rayfin.yml.
Conferma che l'impostazione tenant REST API di Semantic Model Execute Queries sia attivata.
Conferma che l'utente abbia i permessi di Build e Read sul modello semantico.
Verifica che il DAX faccia riferimento a tabelle, colonne e misure esistenti.
Controlla la categoria di errore e il messaggio del risultato del connettore.
Controlla la console del browser per errori lato client.

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-09-29