Criar um aplicativo conectado a um modelo semântico

Use o modelo de aplicativo de dados com um conector de modelo semântico do Fabric para criar um aplicativo analítico do Fabric. O modelo fornece padrões de visualização, formatação, grade de dados e validação do navegador. O conector fornece acesso digitado e delegado a um modelo semântico por meio do cliente Fabric Apps.

Fora de caixa, os aplicativos criados com o modelo incluem:

• Autenticação do Fabric
• Orientações para geração de DAX (Expressões de Análise de Dados) de alta qualidade.
• Componentes visuais prontos para empresas, projetados para aplicações analíticas.
• Padrões de grade de dados, tematização, formatação e validação no navegador.

Por que usar o modelo de aplicativo de dados?

Sem essas capacidades integradas, um agente de codificação deve 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 quebrados ou vazios.
• Comportamento inconsistente nos gráficos.
• Consultas desnecessárias de DAX durante o desenvolvimento e a execução.

O modelo oferece padrões reutilizáveis que melhoram a confiabilidade, produzem visuais mais coesos alinhados às melhores práticas de relatórios e reduzem a sobrecarga de consultas. O conector padroniza a configuração semântica do modelo e o acesso em tempo de execução.

Pré-requisitos

• Node.js 20 ou posterior.
• Acesso ao Fabric.
• Um workspace Fabric em que você tem permissões de Colaborador, Membro ou Administrador.
• A carga de trabalho de Aplicativos do Fabric está habilitada em seu locatário. Veja Criar seu primeiro aplicativo Fabric.
• A configuração de locatário da API REST de Execução de Modelo Semântico está habilitada.
• Permissões de construção e leitura em um modelo semântico hospedado na capacidade do Fabric ou do Power BI.
• O ID do workspace e o ID do item para o modelo semântico.

Criar o aplicativo

Crie um projeto a partir do modelo de data app:

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

Substitua <app-name> e <workspace-name> pelos nomes do seu app e do seu espaço de trabalho do Fabric. Depois, abra a nova pasta do projeto:

cd <app-name>

Adicionar o conector semântico do modelo

Se você não souber o ID do item de modelo semântico, liste os modelos semânticos no workspace:

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 seu esquema em rayfin/connectors/salesModel/.
• Exibe um comando npm install com versão correspondente para os pacotes do conector.

Execute o comando de instalação exato exibido pela CLI.

A configuração gerada se assemelha 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

Mantenha o valor gerado version .

Conecte o template ao modelo semântico

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

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

Use a URL da API e a chave publicável do seu projeto Fabric Apps. Mantenha o fluxo de login existente do Fabric no modelo.

Envie o DAX por meio do 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);
}

Substitua Sales por uma tabela no seu modelo semântico. Verifique o status retornado antes de passar colunas e linhas para um visual.

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

Construa o app com um agente de codificação

O andaime inclui instruções e habilidades para agentes de codificação. Abra o projeto no seu agente preferido e descreva o público, as perguntas, as interações e as visualizações do app.

Por exemplo, você pode:

• Abra o projeto no Visual Studio Code e depois abra o painel do GitHub Copilot Chat.
• Abra um terminal no projeto e então execute copilot.

Use 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.

Use os recursos do modelo

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

Fabric Apps são aplicações web padrão, então você pode implementar recursos fora desses padrões. Recursos que não estão incluídos no template podem exigir mais engenharia personalizada e validação.

Visuais

O modelo inclui destaque cruzado e primitivas pré-configuradas para:

• Gráficos de barras, incluindo layouts verticais, horizontais, agrupados e empilhados.
• Gráficos de linhas com marcadores opcionais.
• Gráficos de área.
• Gráficos de dispersão.
• Gráficos de torta e rosquinhas.
• Mapas de calor.
• Gráficos de bolhas.
• Gráficos de cachoeiras.
• Cartões de valor único para chamadas de KPI.
• Visuais em camadas e compostos, como barras com rótulos de dados e gráficos de linhas de dois eixos.

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

Você pode pedir ao seu agente de programação para gerar outras visualizações. Visuais sem um primitivo template podem exigir mais iterações e validação.

Recursos do data grid

O modelo inclui uma grade de dados com as seguintes capacidades pré-configuradas:

• Cabeçalhos de coluna derivados de metadados semânticos de modelos.
• Formatação de números e datas aplicada por coluna por meio de strings de formatação.
• Ordenação.
• Linhas roláveis com controle de overflow.
• Suporte para temas de luz e sombra.
• Renderizadores de células personalizados para:
  • Barras de dados para valores numéricos.
  • Indicadores booleanos.
  • URLs clicáveis.
  • Células de imagem com uma sobreposição de caixa de luz.
  • Células com vários campos, como nome e função em uma única coluna.

Você pode adicionar outras capacidades de grade de dados, mas elas podem exigir mais engenharia personalizada.

Temas

Dê ao seu agente de codificação requisitos de marca ou estilo, como paleta de cores, estilo de canto ou fonte. O template mantém estilos compartilhados em um único local central, então as mudanças fluem para cartões, botões, gráficos, grades de dados e dicas de ferramentas.

O estilo centralizado evita cores descompatí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 resultado. O template pode reutilizar cadeias de formatos semânticos do modelo em eixos de gráficos, tooltips, etiquetas de dados, cartões e células da grade de dados.

Por exemplo, uma única definição de formato mantém 1500.5 exibido como $1,500.50 e 0.25 exibido como 25% sempre que esses valores aparecerem.

Validação do navegador

Antes de publicar o app, use o fluxo de trabalho de validação do navegador Playwright incluído para abri-lo em um navegador real e conferir:

• Os visuais são renderizados corretamente.
• Os gráficos não são cortados nem comprimidos.
• O texto é legível.
• As tabelas de dados lidam com o transbordamento.
• Os estados de carregamento, vazio e erro são fáceis de usar.
• Filtros, destaque cruzado e formatação de dados funcionam conforme esperado.
• O console do navegador não apresenta erros inesperados.

Esse fluxo de trabalho detecta problemas de layout e renderização antes que os usuários os vejam. A validação do navegador confirma o comportamento da interface. Teste o conector implantado separadamente com um usuário que tenha acesso tanto ao aplicativo Fabric quanto ao modelo semântico.

Implante e verifique o aplicativo

Implante o aplicativo e a configuração do conector:

npx rayfin up

Abra o aplicativo implantado pelo portal Fabric. Faça login, execute cada interação do usuário e compare resultados importantes com o modelo semântico.

Se uma consulta falhar:

• Confirme os IDs de itens do workspace e do modelo semântico em rayfin.yml.
• Confirme que a configuração de tenant REST da API Semântic Model Execute Queries está ativada.
• Confirme que o usuário tem as permissões de Compilar 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.
• Verifique o console do navegador para erros do lado do cliente.

Conteúdo relacionado

• Conecte aplicativos Fabric aos dados Fabric
• Crie um aplicativo de modelo semântico com o GitHub Copilot
• Autenticação para Aplicativos Fabric
• Implantar um aplicativo do Fabric no Fabric