データアプリのテンプレートとFabricセマンティックモデルコネクタを組み合わせて、分析用Fabricアプリを構築します。 このテンプレートは、可視化、フォーマット、データグリッド、ブラウザ検証パターンを提供します。 コネクターは、Fabric Appsクライアントを通じて型付きで委任されたセマンティックモデルへのアクセスを提供します。
すぐに使用できるように、テンプレートで作成されたアプリには次のものが含まれます。
- Fabric認証。
- より高品質なDAX(データ分析式)生成ガイダンス。
- 分析アプリケーション向けに設計されたエンタープライズ対応のビジュアルコンポーネント。
- データグリッド、テーマ設定、フォーマット、ブラウザ検証パターン。
Note
現在、Rayfin CLIがデータアプリテンプレートを使ってアプリを作成するサポートされています。
データ アプリ テンプレートを使用する理由
これらの組み込み機能がなければ、コーディングエージェントは認証、DAX生成、可視化設計を毎回のセッションでゼロから解決しなければなりません。 その結果、次のような結果が生まれる可能性があります:
- 失敗が増え、映像が壊れていたり空っぽだったりします。
- チャートの挙動が一貫していない。
- 開発および実行時の不要なDAXクエリ。
このテンプレートは信頼性を向上させ、報告のベストプラクティスに沿ったより一貫したビジュアルを作成し、クエリのオーバーヘッドを削減する再利用可能なパターンを提供します。 コネクターはセマンティックモデルの設定とランタイムアクセスを標準化します。
前提条件
- Node.js 20 以降。
- Fabricへのアクセス。
- 共同作成者、メンバー、または管理者のアクセス許可を持つFabric ワークスペース。
- お客様のテナントで有効化されている Fabric Apps ワークロード 「最初のFabricアプリを作成」をご覧ください。
- セマンティック モデル実行クエリ REST API テナント設定が有効になっています。
- FabricやPower BIの容量でホストされるセマンティックモデル上で権限を構築・読み取りします。
- セマンティックモデルのワークスペースIDとアイテムID。
アプリを作成する
データアプリのテンプレートからプロジェクトを作成してください:
npm create @microsoft/rayfin@latest -- "<app-name>" --template dataapp --workspace <workspace-name>
<app-name> と <workspace-name> を、アプリ名と Fabric ワークスペース名に置き換えてください。 次に新しいプロジェクトフォルダを開きます:
cd <app-name>
セマンティックモデルコネクターを追加してください
セマンティックモデルのアイテムIDがわからない場合は、ワークスペースにセマンティックモデルをリストアップしてください:
npx rayfin connector search --workspace-id <workspace-id> --type fabric-semanticmodel --json
セマンティックモデルをコネクターとして追加します:
npx rayfin connector add --type fabric-semanticmodel --workspace-id <workspace-id> --item-id <semantic-model-item-id> --name salesModel --operations executeQuery
コマンド:
-
rayfin/rayfin.ymlにsalesModelコネクタを追加します。 -
rayfin/connectors/salesModel/の下でスキーマを作成します。 - コネクタパッケージのバージョンマッチされた
npm installコマンドを出力します。
CLIで出力された正確なインストールコマンドを実行してください。
生成された構成は以下の例に似ています。
connectors:
- name: salesModel
type: fabric-semanticmodel
config:
workspaceId: "<workspace-id>"
itemId: "<semantic-model-item-id>"
auth:
type: delegated
version: "1"
operations:
- name: executeQuery
生成された version 値は保持してください。
テンプレートをセマンティックモデルに接続します
テンプレートには分析コンポーネントやエージェントのガイダンスが含まれており、コネクターで再利用できます。 データアクセス層を設定して ConnectorsRayfinClient を作成し、セマンティックモデルのランタイムを登録します:
重要
セマンティックモデルクエリにはコネクタクライアントを使いましょう。 スキャフォールドに別のセマンティックモデルクライアントが含まれている場合は、2つのデータアクセスパスを維持するのではなく、そのクライアントへの呼び出しを置き換えてください。
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(),
}
);
Fabric AppsプロジェクトのAPIのURLと公開可能なキーを使ってください。 テンプレートの既存のFabricサインインの流れを維持してください。
コネクターを通じてDAXを送信してください:
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);
}
Salesを意味論モデルのテーブルに置き換えてください。 列や行をビジュアルに渡す前に、返送された状態を確認してください。
コネクタの設定やセキュリティガイダンスについては、「Fabric Apps to Fabric Data」をご覧ください。
コーディングエージェントでアプリを構築しましょう
この足場には、コーディングエージェントのための指示やスキルが含まれています。 希望するエージェントでプロジェクトを開き、対象者、質問、やり取り、アプリのビジュアライゼーションを説明してください。
例えば、あなたは次のことができます:
- Visual Studio Codeでプロジェクトを開き、その後GitHubのCopilot Chatパネを開きます。
- プロジェクト内でターミナルを開いてから
copilotを実行します。
このプロンプトを出発点として使ってください:
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.
テンプレート機能を使う
データアプリのテンプレートには、分析アプリケーション用の再利用可能なパターンが含まれています。
Fabricアプリは標準的なウェブアプリケーションなので、これらのパターン以外の機能を実装できます。 テンプレートに含まれていない機能は、より多くのカスタムエンジニアリングや検証が必要になるかもしれません。
Visuals
テンプレートには、以下のクロスハイライトおよび事前設定プリミティブが含まれています:
- 縦、横、グループ、積み重ねの配置を含む棒グラフ。
- 折れ線図で、オプションのマーカー付き。
- エリアチャート。
- 散布図。
- パイとドーナツのチャート。
- ヒートマップ。
- バブルチャート。
- 滝のチャート。
- KPIコールアウト用の単一価値カード。
- データラベル付きのバーや二軸線図などのレイヤードや複合ビジュアル。
連結された意味モデルに存在するフィールドや測度を用いましょう。 失敗したコネクタクエリをモックデータに置き換えないでください。
コーディングエージェントに他のビジュアルを作成してもらうこともできます。 テンプレートプリミティブなしのビジュアルは、より多くの反復や検証が必要になるかもしれません。
データ グリッド機能
テンプレートには、以下のような事前設定機能を備えたデータグリッドが含まれています:
- セマンティックモデルのメタデータから派生した列ヘッダー。
- フォーマット文字列を通じて、カラムごとに番号と日付のフォーマットが適用されます。
- 並べ替え。
- オーバーフロー処理付きのスクロール可能な行。
- ライトとダークのテーマをサポートしています。
- 次の対象のカスタムセルレンダラー:
- 数値を表すデータ バー。
- ブール指標。
- クリック可能なURLです。
- ライトボックスオーバーレイ付きの画像セル。
- 名前や役割が1列に並ぶような多フィールドセル。
他のデータグリッド機能を追加することもできますが、それにはよりカスタムエンジニアリングが必要になるかもしれません。
テーマ化
コーディングエージェントには、カラーパレット、コーナースタイル、フォントなどのブランドやスタイリングの要件を伝えましょう。 テンプレートは共有スタイルを一箇所にまとめているため、カード、ボタン、チャート、データグリッド、ツールチップへの流れを切り替えます。
集中型スタイリングは、各コンポーネント別にスタイリングした際に生じる色の不一致、フォントの不一致、レイアウトの違いを回避します。
文字列の書式設定
結果列ごとにフォーマットを定義します。 このテンプレートは、チャート軸、ツールチップ、データラベル、カード、データグリッドセル間でセマンティックモデルフォーマットの文字列を再利用できます。
例えば、単一のフォーマット定義では、それらの値がどこに現れても、1500.5を$1,500.50として表示し、0.25を25%として表示します。
ブラウザ検証
アプリを公開する前に、付属のPlaywrightブラウザ検証ワークフローを使って実際のブラウザで開き、以下を確認してください:
- ビジュアルは正しく描画されます。
- チャートは切り離されたり圧縮されたりしません。
- テキストは読めます。
- データグリッドはオーバーフローを処理します。
- 読み込み、空、エラーの状態は利用可能です。
- フィルター、クロスハイライト、データのフォーマットは期待通りに機能します。
- ブラウザコンソールには予期せぬエラーはありません。
このワークフローは、ユーザーの目に触れる前にレイアウトやレンダリングの問題を検出します。 ブラウザの検証でフロントエンドの動作が確認されます。 Fabricアプリとセマンティックモデルの両方にアクセスできるユーザーと別途、展開済みコネクタをテストしてください。
アプリのデプロイと検証
アプリとコネクタの設定を展開する:
npx rayfin up
Fabricポータルからデプロイされたアプリを開いてください。 サインインし、各ユーザーインタラクションを実行し、重要な結果をセマンティックモデルと比較します。
クエリが失敗した場合:
-
rayfin.ymlでワークスペースとセマンティックモデルのアイテムIDを確認してください。 - Semantic Model Execute Queries REST APIのテナント設定が有効になっているか確認してください。
- ユーザーがセマンティックモデルに対してビルドおよび読み取り権限を持っているか確認してください。
- DAXが既存のテーブル、列、指標を参照しているか確認してください。
- コネクタの結果のエラーカテゴリとメッセージを確認してください。
- クライアント側のエラーがないかブラウザコンソールを確認してください。