Criar uma aplicação ligada a um modelo semântico

Use o modelo de data app com um conector de modelo semântico Fabric para construir uma aplicação Fabric analítica. O modelo fornece padrões de visualização, formatação, grelha de dados e validação do navegador. O conector fornece acesso digitado e delegado a um modelo semântico através do cliente Fabric Apps.

De fábrica, as aplicações criadas com o modelo incluem:

Autenticação do Fabric.
Orientação de elevada qualidade para a geração de DAX (Expressões de Análise de Dados).
Componentes visuais prontos para empresas, concebidos para aplicações analíticas.
Grelha de dados, tematização, formatação e padrões de validação do navegador.

Observação

Atualmente, a CLI Rayfin é a forma suportada de criar aplicações usando o modelo de aplicação de dados.

Porque usar o modelo da aplicação de dados?

Sem estas capacidades integradas, um agente de programação tem de resolver autenticação, geração de DAX e design de visualização do zero em cada sessão. Isso pode levar a:

Mais falhas e elementos visuais danificados ou vazios.
Comportamento inconsistente nos gráficos.
Consultas DAX desnecessárias durante o desenvolvimento e o tempo de execução.

O modelo fornece padrões reutilizáveis que melhoram a fiabilidade, produzem visuais mais coesos alinhados com as melhores práticas de reporte e reduzem a sobrecarga de consultas. O conetor normaliza a configuração do modelo semântico e o acesso em tempo de execução.

Pré-requisitos

Node.js 20 ou posterior.
Acesso ao Fabric.
Um espaço de trabalho Fabric onde tens permissões de Contribuidor, Membro ou Administrador.
A carga de trabalho do Fabric Apps ativada no seu tenant. Veja Criar a sua primeira aplicação Fabric.
A definição de tenant da API REST para Executar Modelos Semânticos (SEMANTIC Model Execute Queries) está ativada.
Permissões de construção e leitura num modelo semântico alojado em capacidade de Fabric ou Power BI.
O ID do espaço de trabalho e o ID do item para o modelo semântico.

Criar a aplicação

Crie um projeto a partir do modelo da aplicação de dados:

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

Substitua <app-name> e <workspace-name> pelos nomes da sua aplicação e do espaço de trabalho Fabric. Depois abre a nova pasta do projeto:

cd <app-name>

Adicionar o conector do modelo semântico

Se não souber o ID do item semântico do modelo, liste os modelos semânticos no espaço de trabalho:

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

Adicione o modelo semântico como um conector:

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

O comando:

Adiciona o salesModel conector a rayfin/rayfin.yml.
Cria o esquema em rayfin/connectors/salesModel/.
Imprime um comando compatível npm install com a versão para os pacotes conectores.

Executa exatamente o comando de instalação impresso pelo CLI.

A configuração gerada assemelha-se ao seguinte exemplo:

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

Mantém o valor gerado version .

Liga o template ao modelo semântico

O modelo contém componentes analíticos e orientações para agentes que pode reutilizar com o conector. Configure a sua camada de acesso a dados para criar um ConnectorsRayfinClient e registar o tempo de execução do modelo semântico:

Importante

Use o cliente conector para consultas semânticas de modelos. Se o andaime incluir outro cliente de modelo semântico, substitua as chamadas para ele em vez de manter dois caminhos de acesso aos dados.

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 a URL da API e a chave publicável do teu projeto Fabric Apps. Mantém o fluxo de login já existente no Fabric do template.

Envie DAX pelo 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);
}

Substitui Sales por uma tabela no teu modelo semântico. Verifique o estado devolvido antes de passar colunas e linhas para um visual.

Para mais orientações sobre configuração de conectores e segurança, consulte Connect Fabric Apps to Fabric data.

Constrói a aplicação com um agente de programação

O andaime inclui instruções e competências para agentes de programação. Abra o projeto no seu agente preferido e descreva o público, as perguntas, as interações e as visualizações da aplicação.

Por exemplo, você pode:

Abre o projeto no Visual Studio Code e depois abre o painel do GitHub Copilot Chat.
Abra um terminal no projeto e depois execute copilot.

Usa este prompt como ponto 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.

Utilizar as capacidades do template

O modelo da aplicação de dados inclui padrões reutilizáveis para aplicações analíticas.

As Fabric Apps são aplicações web padrão, por isso pode implementar funcionalidades fora desses padrões. Funcionalidades que não estão incluídas no modelo podem exigir mais engenharia personalizada e validação.

Elementos visuais

O modelo inclui realçamento cruzado e primitivas pré-configuradas para:

Gráficos de barras, incluindo orientações verticais e horizontais, bem como disposições agrupadas e empilhadas.
Gráficos de linhas com marcadores opcionais.
Gráficos de área.
Gráficos de dispersão.
Gráficos de tartes e donuts.
Mapas de calor.
Gráficos de bolhas.
Mapas de cascatas.
Cartões de valor único para chamadas de KPI.
Visuais em camadas e compostos, como barras com etiquetas de dados e gráficos de linhas de dois eixos.

Use campos e medidas que existam no modelo semântico conexo. Não substituas uma consulta de conector falhada por dados simulados.

Podes pedir ao teu agente de código para gerar outros elementos visuais. Visuais sem um primitivo modelo podem exigir mais iterações e validação.

Capacidades da grelha de dados

O modelo inclui uma grelha de dados com estas capacidades pré-configuradas:

Cabeçalhos de coluna derivados de metadados semânticos de modelos.
Formatação de números e datas aplicada a cada coluna por meio de cadeias de formatação.
A ordenar.
Linhas deslizáveis com tratamento de excesso.
Suporte para temas de luz e sombra.
Renderizadores de células personalizados para:
- Barras de dados para valores numéricos.
- Indicadores booleanos.
- URLs em que é possível clicar.
- Células de imagem com uma sobreposição de lightbox.
- Células com vários campos, como um nome e uma função numa coluna.

Podes adicionar outras capacidades de redes de dados, mas podem exigir mais engenharia personalizada.

Tematização

Dê ao seu agente de codificação requisitos de marca ou estilo, como uma paleta de cores, estilo de canto ou fonte. O modelo mantém estilos partilhados num único local central para que as alterações fluam para cartões, botões, gráficos, grelhas de dados e dicas de ferramentas.

A estilização centralizada evita cores incompatíveis, fontes inconsistentes e diferenças de layout que podem ocorrer quando cada componente é estilizado separadamente.

Formatar cadeias de caracteres

Defina formatação uma vez por coluna de resultados. O modelo pode reutilizar cadeias de formato do modelo semântico nos eixos dos gráficos, nas descrições, nos rótulos de dados, nos cartões e nas células da grelha de dados.

Por exemplo, uma única definição de formato faz com que 1500.5 seja apresentado como $1,500.50 e 0.25 seja apresentado como 25% sempre que esses valores aparecem.

Validação do navegador

Antes de publicar a aplicação, use o fluxo de trabalho de validação do navegador Playwright incluído para a abrir num navegador real e verificar:

Os visuais são renderizados corretamente.
Os gráficos não são cortados nem comprimidos.
O texto é legível.
As grelhas de dados gerem o transbordo.
Os estados de carregamento, vazio e erro são utilizáveis.
Filtros, ressaltos cruzados e formatação de dados funcionam como esperado.
A consola do navegador não apresenta erros inesperados.

Este fluxo de trabalho deteta problemas de layout e renderização antes que os utilizadores os vejam. A validação do navegador confirma o comportamento do frontend. Teste o conector implementado separadamente com um utilizador que tenha acesso tanto à aplicação Fabric como ao modelo semântico.

Implemente e verifique a aplicação

Implemente a aplicação e a configuração do conector:

npx rayfin up

Abra a aplicação implementada a partir do portal Fabric. Iniciar sessão, executar cada interação do utilizador e comparar resultados importantes com o modelo semântico.

Se uma consulta falhar:

Confirme o ID do espaço de trabalho e o ID do item de modelo semântico em rayfin.yml.
Confirme que a definição de tenant REST da API Semantic Model Execute Queries está ativada.
Confirme que o utilizador tem permissões de Construção e Leitura no modelo semântico.
Verifique se o DAX faz referência a tabelas, colunas e medidas existentes.
Verifique a categoria de erro e a mensagem do resultado do conector.
Verifica a consola do navegador para erros do lado do cliente.

Comentários

Esta página foi útil?

Última atualização a 2026-09-29