Créer une application connectée à un modèle sémantique

Utilisez le modèle d’application données avec un connecteur de modèle sémantique Fabric pour construire une application Fabric analytique. Le modèle fournit des motifs de visualisation, de mise en forme, de grille de données et de validation par navigateur. Le connecteur fournit un accès décrit et délégué à un modèle sémantique via le client Fabric Apps.

Les applications créées avec le modèle sont les suivantes :

Authentification de Fabric.
Des directives de génération DAX (Data Analysis Expressions) de meilleure qualité.
Composants visuels prêts pour l’entreprise conçus pour des applications analytiques.
Grille de données, thème, mise en forme et motifs de validation du navigateur.

Note

Actuellement, la CLI Rayfin est la méthode prise en charge pour créer des applications en utilisant le modèle d’application de données.

Pourquoi utiliser le modèle d’application de données ?

Sans ces capacités intégrées, un agent de codage doit résoudre l’authentification, la génération DAX et la conception de visualisation à partir de zéro à chaque session. Cela peut mener à :

Davantage d’échecs et de visuels défectueux ou vides.
Comportement incohérent dans les graphiques.
Requêtes DAX inutiles pendant le développement et l’exécution.

Le modèle propose des motifs réutilisables qui améliorent la fiabilité, produisent des visuels plus cohérents alignés sur les meilleures pratiques de reporting et réduisent la charge des requêtes. Le connecteur standardise la configuration sémantique des modèles et l’accès à l’exécution.

Prerequisites

Node.js 20 ou version ultérieure.
Accès à Fabric.
Un espace de travail Fabric où vous disposez des autorisations Contributeur, Membre ou Administrateur.
Charge de travail Fabric Apps activée dans votre tenant. Voir Créer votre première application Fabric.
Le paramètre client de l’API REST Exécuter des requêtes du modèle sémantique est activé.
Autorisations de compilation et de lecture sur un modèle sémantique hébergé sur Fabric ou Power BI Capacity.
L’ID de l’espace de travail et l’ID d’élément pour le modèle sémantique.

Créer l’application

Créez un projet à partir du modèle d’application de données :

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

Remplacez <app-name> et <workspace-name> par les noms de votre application et de votre espace de travail Fabric. Puis ouvrez le nouveau dossier du projet :

cd <app-name>

Ajouter le connecteur de modèle sémantique

Si vous ne connaissez pas l’identifiant de l’élément sémantique, listez les modèles sémantiques dans l’espace de travail :

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

Ajoutez le modèle sémantique comme connecteur :

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

Commande :

Ajoute le salesModel connecteur à rayfin/rayfin.yml.
Crée son schéma sous rayfin/connectors/salesModel/.
Imprime une commande correspondante npm install à la version pour les packages connecteurs.

Exécutez exactement la commande d’installation imprimée par la CLI.

La configuration engendrée ressemble à l’exemple suivant :

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

Conservez la valeur générée version .

Connectez le modèle au modèle sémantique

Le modèle contient des composants analytiques et des instructions pour l’agent que vous pouvez réutiliser avec le connecteur. Configurez sa couche d’accès aux données pour créer un ConnectorsRayfinClient et enregistrer l’exécution du modèle sémantique :

Important

Utilisez le client connecteur pour les requêtes sémantiques des modèles. Si l’échafaudage inclut un autre client modèle sémantique, remplacez les appels vers celui-ci au lieu de maintenir deux chemins d’accès aux données.

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

Utilisez l’URL de l’API et la clé publiable de votre projet Fabric Apps. Conservez le flux de connexion Fabric existant du modèle.

Envoyez DAX via le connecteur :

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

Remplacez-le Sales par une table dans votre modèle sémantique. Vérifiez l’état renvoyé avant de transmettre les colonnes et les lignes à un élément visuel.

Pour plus de conseils sur la configuration des connecteurs et la sécurité, voir Connect Fabric Apps to Fabric data.

Construis l’application avec un agent de codage

L’échafaudage comprend des instructions et des compétences pour les agents de codage. Ouvrez le projet dans votre agent préféré, et décrivez le public, les questions, les interactions et les visualisations de l’application.

Par exemple, vous pouvez :

Ouvre le projet dans Visual Studio Code, puis ouvre le panneau GitHub Copilot Chat.
Ouvrez un terminal dans le projet, puis exécutez copilot.

Utilisez cette consigne comme point de départ :

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.

Utilisez les capacités du modèle

Le modèle d’application de données inclut des motifs réutilisables pour des applications analytiques.

Les applications Fabric sont des applications web standard, vous pouvez donc implémenter des fonctionnalités en dehors de ces motifs. Les fonctionnalités non incluses dans le modèle peuvent nécessiter plus d’ingénierie personnalisée et de validation.

Objets visuels

Le modèle inclut des surlignements croisés et des primitives préconfigurées pour :

Diagrammes à barres, incluant les plans verticaux, horizontaux, groupés et empilés.
Des graphiques de lignes avec des marqueurs optionnels.
Cartes de zone.
Cartes dispersées.
Diagrammes en tort et en forme de donuts.
Cartes thermiques.
Des graphiques à bulles.
Cartes de cascades.
Cartes à valeur unique pour les KPI mis en avant.
Des visuels superposés et composites, tels que des barres avec des étiquettes de données et des graphiques de lignes à double axe.

Utilisez des champs et des mesures qui existent dans le modèle sémantique connexe. Ne remplacez pas une requête de connecteur défaillante par des données fictives.

Vous pouvez demander à votre agent de codage de générer d’autres visuels. Les visuels sans primitive modèle peuvent nécessiter plus d’itérations et de validations.

Fonctionnalités de grille de données

Le modèle inclut une grille de données avec ces capacités préconfigurées :

En-têtes de colonnes dérivés des métadonnées sémantiques du modèle.
Formatage des nombres et des dates appliqué par colonne à l’aide de chaînes de format.
Tri.
Lignes défilables avec gestion du débordement.
Prise en charge des thèmes lumière et obscurité.
Moteurs de rendu de cellules personnalisés pour :
- Barres de données pour les valeurs numériques.
- Indicateurs booléens.
- Liens URL cliquables.
- Cellules d’image avec une superposition de boîte lumineuse.
- Cellules à plusieurs champs, par exemple un nom et un rôle dans une colonne.

Vous pouvez ajouter d’autres capacités de grille de données, mais elles pourraient nécessiter plus d’ingénierie personnalisée.

Thèmes

Donnez à votre agent de codage des exigences de marque ou de style, comme une palette de couleurs, un style de coin ou une police. Le modèle conserve les styles partagés dans un emplacement central unique, de sorte que les modifications se répercutent sur les cartes, les boutons, les graphiques, les grilles de données et les infobulles.

Le style centralisé évite les couleurs incompatibles, les polices incohérentes et les différences de mise en page qui peuvent survenir lorsque chaque composant est stylisé séparément.

Chaînes de format

Définissez la mise en forme une fois par colonne de résultat. Le modèle peut réutiliser les chaînes de format du modèle sémantique dans les axes de graphique, les infobulles, les étiquettes de données, les cartes et les cellules de grille de données.

Par exemple, une définition de format unique permet de conserver l’affichage de 1500.5 sous la forme $1,500.50 et de 0.25 sous la forme 25% partout où ces valeurs apparaissent.

Validation par navigateur

Avant de publier l’application, utilisez le flux de validation du navigateur Playwright inclus pour l’ouvrir dans un vrai navigateur et vérifier :

Les visuels s’affichent correctement.
Les graphiques ne sont pas coupés ni compressés.
Le texte est lisible.
Les grilles de données gèrent le débordement.
Les états de chargement, vide et d’erreur sont utilisables.
Les filtres, les surlignages croisés et la mise en forme des données fonctionnent comme prévu.
La console du navigateur ne présente aucune erreur inattendue.

Ce flux de travail détecte les problèmes de mise en page et de rendu avant que les utilisateurs ne les voient. La validation par navigateur confirme le comportement du frontend. Testez séparément le connecteur déployé avec un utilisateur ayant accès à la fois à l’application Fabric et au modèle sémantique.

Déploie et vérifie l’application

Déploie l’application et la configuration du connecteur :

npx rayfin up

Ouvrez l’application déployée depuis le portail Fabric. Connectez-vous, exécutez chaque interaction utilisateur et comparez les résultats importants avec le modèle sémantique.

Si une requête échoue :

Confirmez les identifiants d’éléments de l’espace de travail et du modèle sémantique dans rayfin.yml.
Confirmez que le paramètre de locataire de l’API REST Semantic Model Execute Queries est activé.
Confirmez que l’utilisateur dispose des permissions de construction et de lecture sur le modèle sémantique.
Vérifiez que le DAX fait référence aux tables, colonnes et mesures existantes.
Vérifiez la catégorie d’erreur et le message du résultat du connecteur.
Vérifiez la console du navigateur pour détecter des erreurs côté client.

Commentaires

Est-ce que cette page vous a été utile?

Dernière mise à jour : 2026-09-29