Vytvoření aplikace připojené k sémantickému modelu

Použijte šablonu datové aplikace s Fabric sémantickým modelovým konektorem k vytvoření analytické Fabric aplikace. Šablona poskytuje vizualizaci, formátování, datovou síť a vzory ověřování v prohlížeči. Konektor poskytuje typovaný, delegovaný přístup k sémantickému modelu prostřednictvím klienta Fabric Apps.

Aplikace vytvořené pomocí šablony obsahují:

Ověřování ve službě Fabric.
Pokyny pro generování kvalitnějších výrazů DAX (Data Analysis Expressions).
Vizuální komponenty připravené pro podnik navržené pro analytické aplikace.
Datová síť, témata, formátování a vzory ověřování v prohlížeči.

Poznámka:

V současnosti je podporovaným způsobem vytváření aplikací pomocí šablony datové aplikace Rayfin CLI.

Proč používat šablonu datové aplikace?

Bez těchto vestavěných schopností musí programovací agent řešit autentizaci, generování DAX a vizualizační návrh od začátku v každé relaci. To může vést k:

Další neúspěchy a rozbité nebo prázdné vizuály.
Nekonzistentní chování grafu.
Zbytečné dotazy DAX během vývoje a za běhu.

Šablona poskytuje opakovaně použitelné vzory, které zvyšují spolehlivost, vytvářejí soudržnější vizuály v souladu s osvědčenými postupy reportování a snižují režijní zátěž dotazů. Konektor standardizuje konfiguraci sémantických modelů a přístup za běhu.

Předpoklady

Node.js 20 nebo novější.
Přístup k Fabric
Pracovní prostor Fabric, kde máte oprávnění přispěvatele, člena nebo správce.
Pracovní zatížení Fabric Apps povolené ve vašem tenantovi. Viz Vytvořte si svou první aplikaci Fabric.
Sémantický model spouští dotazy s povoleným nastavením tenanta rozhraní REST API.
Oprávnění pro tvorbu a čtení na sémantickém modelu hostovaném na kapacitě Fabric nebo Power BI.
ID pracovního prostoru a ID položky pro sémantický model.

Vytvoření aplikace

Vytvořte projekt ze šablony datové aplikace:

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

Nahraďte <app-name> a <workspace-name> názvy vaší aplikace a pracovního prostoru Fabric. Pak otevřete složku nového projektu:

cd <app-name>

Přidejte konektor sémantického modelu

Pokud neznáte ID položky sémantického modelu, uveďte v pracovním prostoru sémantické modely:

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

Přidejte sémantický model jako konektor:

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

Příkaz:

Přidá konektor salesModel do rayfin/rayfin.yml.
Vytvoří své schéma pod rayfin/connectors/salesModel/.
Vytiskne příkaz npm install, který odpovídá verzi balíčků konektoru.

Spusťte přesný instalační příkaz, který vypíše CLI.

Generovaná konfigurace připomíná následující příklad:

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

Vygenerovanou version hodnotu si ponechejte.

Připojte šablonu k sémantickému modelu

Šablona obsahuje analytické komponenty a pokyny pro agenty, které můžete znovu použít s konektorem. Nakonfigurujte jeho vrstvu přístupu k datům tak, aby vytvořila ConnectorsRayfinClient a zaregistrovala modul runtime sémantického modelu:

Important

Použijte konektorového klienta pro dotazy na sémantické modely. Pokud generovaný základ obsahuje jiného klienta sémantického modelu, nahraďte jím volání, abyste nemuseli zachovávat dvě cesty přístupu k datům.

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

Použijte API URL a publikovatelný klíč z vašeho projektu Fabric Apps. Zachovejte stávající postup přihlašování k Fabric v šabloně.

Odesílejte DAX přes konektor:

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

Nahraďte Sales ji tabulkou ve svém sémantickém modelu. Předtím než vizuálu předáte sloupce a řádky, zkontrolujte návratový stav.

Další pokyny ke konfiguraci konektorů a zabezpečení najdete v tématu Connect Fabric Apps to Fabric data.

Vytvořte aplikaci pomocí programátora

Kostra obsahuje pokyny a dovednosti pro agenty pro programování. Otevřete projekt ve svém preferovaném agentovi a popište publikum, otázky, interakce a vizualizace aplikace.

Například můžete:

Otevřete projekt ve Visual Studio Code a pak otevřete panel GitHub Copilot Chat.
Otevřete terminál v projektu a poté spusťte copilot.

Použijte tento prompt jako výchozí bod:

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.

Použijte možnosti šablony

Šablona datové aplikace obsahuje opakovaně použitelné vzory pro analytické aplikace.

Fabric Apps jsou standardní webové aplikace, takže můžete implementovat funkce mimo tyto vzory. Funkce, které nejsou v šabloně zahrnuty, mohou vyžadovat více vlastního inženýrství a ověření.

Vizuální prvky

Šablona obsahuje křížové zvýrazňování a přednastavené primitiva pro:

Sloupcové grafy, včetně vertikálních, horizontálních, skupinových a vrstvených rozvržení.
Čárové grafy s volitelnými značkami.
Mapy oblastí.
Bodové grafy.
Koláčové a donutové tabulky.
Heatmapy.
Bublinové grafy.
Vodopádové mapy.
Karty s jednou hodnotou pro KPI callouty.
Vrstvené a kompozitní vizuály, jako jsou sloupce s datovými štítky a čárové grafy s obousměrnými osami.

Používejte pole a míry, které existují v propojeném sémantickém modelu. Nenahrazujte neúspěšný dotaz konektoru fiktivními daty.

Můžete požádat svého programátora, aby vytvořil další vizuály. Vizuály bez šablonového primitivu mohou vyžadovat více iterací a ověření.

Možnosti datové mřížky

Šablona obsahuje datovou síť s těmito předkonfigurovanými schopnostmi:

Záhlaví sloupců odvozená z metadat sémantického modelu.
Formátování čísel a dat se pro každý sloupec použije pomocí formátovacích řetězců.
Třídění.
Posuvné řádky se zpracováním přetečení.
Podpora světlých a tmavých témat.
Vlastní vykreslování buněk pro:
- Datové lišty pro číselné hodnoty.
- Booleovské indikátory.
- Klikatelné URL.
- Buňky obrázků s překrytím typu lightbox.
- Vícepolní buňky, například jméno a role v jednom sloupci.

Můžete přidat další schopnosti datové sítě, ale ty mohou vyžadovat více vlastního inženýrství.

Tématizace

Zadejte svému kódovacímu agentovi požadavky na značku nebo styl, například barevnou paletu, styl rohů nebo písmo. Šablona udržuje sdílené styly na jednom centrálním místě, takže se změny promítají do karet, tlačítek, grafů, datových tabulek a popisků.

Centralizované stylování zabraňuje nesouladu barev, nekonzistentním fontům a rozdílům v rozvržení, které mohou nastat, když je každá komponenta stylizována zvlášť.

Formátování řetězců

Definujte formátování jednou na sloupec výsledků. Šablona může opakovaně používat řetězce formátu sémantického modelu v osách grafů, popiscích, datových štítcích, kartách a buňkách datové mřížky.

Například jedna definice formátu zajišťuje, že se 1500.5 zobrazuje jako $1,500.50 a 0.25 jako 25% všude, kde se tyto hodnoty vyskytují.

Ověřování prohlížeče

Před zveřejněním aplikace použijte přiložený workflow ověřování prohlížeče Playwright, abyste ji otevřeli v reálném prohlížeči a zkontrolovali:

Vizuály jsou správně vykreslené.
Grafy nejsou odříznuté ani komprimované.
Text je čitelný.
Datové mřížky řeší přetečení.
Načítací, prázdné a chybové stavy jsou použitelné.
Filtry, zvýrazňování a formátování dat fungují podle očekávání.
Konzole prohlížeče nemá žádné neočekávané chyby.

Tento pracovní postup zachytí problémy s rozložením a vykreslováním dříve, než je uživatelé uvidí. Ověření prohlížeče potvrzuje chování frontendu. Otestujte nasazený konektor zvlášť s uživatelem, který má přístup jak k aplikaci Fabric, tak k sémantickému modelu.

Nasadit a ověřit aplikaci

Nasazení aplikace a konfigurace konektoru:

npx rayfin up

Otevřete nasazenou aplikaci přes portál Fabric. Přihlaste se, spusťte každou uživatelskou interakci a porovnejte důležité výsledky se sémantickým modelem.

Pokud dotaz selže:

Potvrďte ID položek pracovního prostoru a sémantických modelů v rayfin.yml.
Ověřte, že je povolené nastavení tenanta „Semantic Model Execute Queries REST API“.
Potvrďte, že uživatel má oprávnění Build and Read na sémantickém modelu.
Ověřte, že DAX odkazuje na existující tabulky, sloupce a míry.
Zkontrolujte chybovou kategorii a zprávu výsledku konektoru.
Zkontrolujte konzoli prohlížeče na chyby na straně klienta.

Váš názor

Byla tato stránka užitečná?

Poslední aktualizace v 2026-09-29