Creación de una aplicación conectada a un modelo semántico

Utiliza la plantilla de data app con un conector de modelo semántico de Fabric para crear una app analítica de Fabric. La plantilla proporciona patrones de visualización, formato, cuadrícula de datos y validación del navegador. El conector proporciona acceso delegado y tipado a un modelo semántico a través del cliente de Fabric Apps.

De fábrica, las aplicaciones creadas con la plantilla incluyen:

• Autenticación de Fabric.
• Guía de generación de DAX (Expresiones de Análisis de Datos) de mayor calidad.
• Componentes visuales preparados para empresas diseñados para aplicaciones analíticas.
• Cuadrícula de datos, tematización, formato y patrones de validación del navegador.

Note

Actualmente, la CLI de Rayfin es la forma compatible para crear aplicaciones utilizando la plantilla de la app de datos.

¿Por qué usar la plantilla de aplicación de datos?

Sin estas capacidades integradas, un agente de codificación debe resolver desde cero autenticación, generación DAX y diseño de visualización en cada sesión. Eso puede llevar a:

• Más fallos y elementos visuales rotos o vacíos.
• Comportamiento inconsistente en los gráficos.
• Consultas DAX innecesarias durante el desarrollo y la ejecución.

La plantilla proporciona patrones reutilizables que mejoran la fiabilidad, producen imágenes más coherentes alineadas con las mejores prácticas de informes y reducen la carga de consultas. El conector estandariza la configuración semántica del modelo y el acceso en tiempo de ejecución.

Prerequisites

• Node.js 20 o posterior.
• Acceso a Fabric.
• Un área de trabajo de Fabric en la que tiene permisos de colaborador, miembro o administrador.
• La carga de trabajo de Fabric Apps habilitada en su inquilino. Consulta Crea tu primera app de Fabric.
• La configuración del inquilino de la API REST Ejecutar consultas del modelo semántico está habilitada.
• Permisos de creación y lectura en un modelo semántico alojado en una capacidad de Fabric o Power BI.
• El ID del espacio de trabajo y el ID de elemento para el modelo semántico.

Creación de la aplicación

Crea un proyecto a partir de la plantilla de la app de datos:

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

Sustituye <app-name> y <workspace-name> por los nombres de tu app y del espacio de trabajo de Fabric. Luego abre la nueva carpeta del proyecto:

cd <app-name>

Añadir el conector semántico del modelo

Si no conoces el ID semántico del elemento del modelo, lista los modelos semánticos en el espacio de trabajo:

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

Añade el modelo semántico como conector:

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

El comando:

• Añade el salesModel conector a rayfin/rayfin.yml.
• Crea su esquema bajo rayfin/connectors/salesModel/.
• Imprime un comando de npm install versión compatible para los paquetes conectores.

Ejecuta el comando de instalación exacto que imprime la CLI.

La configuración generada se asemeja al siguiente ejemplo:

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

Conserva el valor generado version .

Conecta la plantilla al modelo semántico

La plantilla contiene componentes analíticos y guía de agentes que puedes reutilizar con el conector. Configura su capa de acceso a datos para crear un ConnectorsRayfinClient y registrar el tiempo de ejecución del modelo semántico:

Important

Usa el cliente conector para consultas de modelos semánticos. Si la estructura incluye otro cliente de modelo semántico, sustituya las llamadas a este en lugar de mantener dos rutas de acceso a los datos.

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 la URL de la API y la clave publicable de tu proyecto Fabric Apps. Mantén el flujo de inicio de sesión existente en Fabric de la plantilla.

Envía DAX a través del conector:

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

Sustituye Sales por una tabla en tu modelo semántico. Comprueba el estado devuelto antes de pasar columnas y filas a un objeto visual.

Para más información sobre configuración de conectores y orientación de seguridad, consulta Connect Fabric Apps to Fabric data.

Construye la app con un agente de codificación

El andamiaje incluye instrucciones y habilidades para agentes de codificación. Abre el proyecto en tu agente preferido y describe la audiencia, preguntas, interacciones y visualizaciones de la app.

Por ejemplo, puede hacer lo siguiente:

• Abre el proyecto en Visual Studio Code y luego abre el panel de chat de GitHub Copilot Chat.
• Abre un terminal en el proyecto y luego ejecuta copilot.

Usa este prompt como punto de partida:

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.

Utiliza las capacidades de plantilla

La plantilla de la app de datos incluye patrones reutilizables para aplicaciones analíticas.

Las Fabric Apps son aplicaciones web estándar, así que puedes implementar funciones fuera de estos patrones. Las funciones que no están incluidas en la plantilla pueden requerir más ingeniería personalizada y validación.

Visuals

La plantilla incluye resaltado cruzado y primitivas preconfiguradas para:

• Gráficos de barras, incluyendo diseños verticales, horizontales, agrupados y apilados.
• Diagramas de líneas con marcadores opcionales.
• Gráficos de área.
• Diagramas de dispersión.
• Gráficos de pasteles y donuts.
• Mapas de calor.
• Diagramas de burbujas.
• Gráficos de cascada.
• Tarjetas de valor único para llamadas de KPI.
• Visualizaciones superpuestas y compuestas, como barras con etiquetas de datos y gráficos de líneas con doble eje.

Utiliza campos y medidas que existen en el modelo semántico conectado. No sustituyas una consulta de conector fallida por datos simulados.

Puedes pedirle a tu agente de programación que genere otros visuales. Los visuales sin una primitiva plantilla pueden requerir más iteraciones y validación.

Funcionalidades de la rejilla de datos

La plantilla incluye una cuadrícula de datos con estas capacidades preconfiguradas:

• Cabeceras de columnas derivadas de metadatos semánticos de modelos.
• Formatos de número y fecha aplicados a cada columna mediante cadenas de formato.
• Ordenación.
• Filas desplazables con gestión del desbordamiento.
• Soporte para temas de luz y oscuridad.
• Renderizadores de celdas personalizados para:
  • Barras de datos para valores numéricos.
  • Indicadores booleanos.
  • URLs clicables.
  • Celdas de imagen con una superposición de caja de luz.
  • Celdas de varios campos, como las que contienen un nombre y un cargo en una columna.

Puedes añadir otras capacidades de red de datos, pero pueden requerir más ingeniería personalizada.

Tematización

Indica a tu agente de codificación los requisitos de marca o estilo, como una paleta de colores, un estilo de esquina o una fuente. La plantilla reúne los estilos compartidos en una ubicación central, de modo que los cambios se apliquen a tarjetas, botones, gráficos, rejillas de datos y ayudas emergentes.

El estilo centralizado evita colores desajustados, fuentes inconsistentes y diferencias de diseño que pueden aparecer cuando cada componente se estiliza por separado.

Cadenas de formato

Define el formato una vez por columna de resultado. La plantilla puede reutilizar las cadenas de formato del modelo semántico en los ejes del gráfico, la información sobre herramientas, las etiquetas de datos, las tarjetas y las celdas de la cuadrícula de datos.

Por ejemplo, una única definición de formato mantiene 1500.5 mostrado como $1,500.50 y 0.25 mostrado como 25% siempre que aparezcan esos valores.

Validación de navegador

Antes de publicar la app, utiliza el flujo de trabajo de validación incluido en el navegador de Playwright para abrirla en un navegador real y comprueba:

• Los gráficos se renderizan correctamente.
• Los gráficos no están cortados ni comprimidos.
• El texto es legible.
• Las redes de datos gestionan el desbordamiento.
• Los estados de carga, vacío y error son utilizables.
• Los filtros, el resaltado cruzado y el formato de datos funcionan como se espera.
• La consola del navegador no presenta errores inesperados.

Este flujo de trabajo detecta los problemas de diseño y renderizado antes de que los usuarios los vean. La validación del navegador confirma el comportamiento del frontend. Prueba el conector desplegado por separado con un usuario que tenga acceso tanto a la app Fabric como al modelo semántico.

Despliega y verifica la app

Despliega la aplicación y la configuración del conector:

npx rayfin up

Abre la aplicación desplegada desde el portal de Fabric. Inicia sesión, ejecuta cada interacción del usuario y compara los resultados importantes con el modelo semántico.

Si una consulta falla:

• Confirma los IDs de elementos del espacio de trabajo y del modelo semántico en rayfin.yml.
• Confirma que la configuración del arrendatario de la API REST de ejecución de consultas del modelo semántico está activada.
• Confirma que el usuario tiene permisos de Construcción y Lectura en el modelo semántico.
• Verifica que el DAX haga referencia a tablas, columnas y medidas existentes.
• Revisa la categoría de error y el mensaje del resultado del conector.
• Revisa la consola del navegador para detectar errores del lado del cliente.

Contenido relacionado

• Conecta aplicaciones de Fabric a datos de Fabric
• Crea una aplicación de modelos semánticos con GitHub Copilot
• Autenticación para aplicaciones Fabric
• Implementación de una aplicación de Fabric en Fabric