Membuat aplikasi yang tersambung ke model semantik

Gunakan template aplikasi data dengan konektor model semantik Fabric untuk membangun aplikasi Fabric analitis. Template ini menyediakan pola visualisasi, format, grid data, dan validasi browser. Konektor menyediakan akses yang diketik dan didelegasikan ke model semantik melalui klien Fabric Apps.

Secara default, aplikasi yang dibuat dengan templat mencakup:

Autentikasi Fabric.
Panduan pembuatan DAX (Data Analysis Expressions) berkualitas tinggi.
Komponen visual siap untuk perusahaan yang dirancang untuk aplikasi analitis.
Kisi data, penataan tema, pemformatan, dan pola validasi browser.

Nota

Saat ini, Rayfin CLI adalah cara yang didukung untuk membuat aplikasi menggunakan template aplikasi data.

Mengapa menggunakan templat aplikasi data?

Tanpa kemampuan bawaan ini, agen coding harus menyelesaikan autentikasi, generasi DAX, dan desain visualisasi dari awal di setiap sesi. Hal ini dapat mengarah pada:

Lebih banyak kegagalan dan visual yang rusak atau kosong.
Perilaku grafik yang tidak konsisten.
Kueri DAX yang tidak perlu selama pengembangan dan waktu proses.

Template ini menyediakan pola yang dapat digunakan kembali yang meningkatkan keandalan, menghasilkan visual yang lebih kohesif dan selaras dengan praktik terbaik pelaporan, serta mengurangi beban kueri. Konektor ini menstandarisasi konfigurasi model semantik dan akses runtime.

Prasyarat

Node.js 20 atau yang lebih baru.
Akses ke Fabric.
Ruang kerja Fabric tempat Anda memiliki izin Kontributor, Anggota, atau Admin.
Fitur Fabric Apps yang diaktifkan di tenant Anda Lihat Buat aplikasi Fabric pertama Anda.
Pengaturan penyewa REST API Jalankan Kueri Model Semantik diaktifkan.
Izin membangun dan membaca pada model semantik yang dihosting di kapasitas Fabric atau Power BI.
ID workspace dan ID item untuk model semantik.

Membuat aplikasi

Buat proyek dari template aplikasi data:

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

Ganti <app-name> dan <workspace-name> dengan nama untuk aplikasi dan ruang kerja Fabric Anda. Kemudian buka folder proyek baru:

cd <app-name>

Tambahkan konektor model semantik

Jika Anda tidak mengetahui ID item model semantik, daftarkan model semantik di workspace:

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

Tambahkan model semantik sebagai konektor:

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

Perintah:

Menambahkan salesModel konektor ke rayfin/rayfin.yml.
Membuat skemanya di bawah rayfin/connectors/salesModel/.
Menampilkan perintah npm install yang versinya sesuai untuk paket konektor.

Jalankan perintah instalasi persis yang dicetak oleh CLI.

Konfigurasi yang dihasilkan menyerupai contoh berikut:

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

Pertahankan nilai yang dihasilkan version .

Hubungkan template ke model semantik

Template berisi komponen analitis dan panduan agen yang dapat Anda gunakan kembali dengan konektor. Konfigurasikan lapisan akses datanya untuk membuat ConnectorsRayfinClient dan mendaftarkan runtime model semantik:

Important

Gunakan klien konektor untuk kueri model semantik. Jika scaffold mencakup klien model semantik lain, gantikan pemanggilan ke klien tersebut alih-alih mempertahankan dua jalur akses data.

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

Gunakan URL API dan kunci yang dapat dipublikasikan dari proyek Fabric Apps Anda. Pertahankan alur masuk Fabric yang sudah ada pada template.

Kirim DAX melalui 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);
}

Ganti Sales dengan tabel di model semantik Anda. Periksa status yang dikembalikan sebelum Anda meneruskan kolom dan baris ke elemen visual.

Untuk panduan konfigurasi konektor dan keamanan lebih lanjut, lihat Connect Fabric Apps to Fabric data.

Bangun aplikasi dengan agen coding

Kerangka tersebut mencakup instruksi dan keterampilan untuk agen pemrograman. Buka proyek di agen pilihan Anda, dan jelaskan audiens, pertanyaan, interaksi, serta visualisasi untuk aplikasi tersebut.

Misalnya, Anda dapat:

Buka proyek di Visual Studio Code, lalu buka panel GitHub Copilot Chat.
Buka terminal di proyek, lalu jalankan copilot.

Gunakan prompt ini sebagai titik awal:

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.

Gunakan kemampuan template

Template aplikasi data mencakup pola yang dapat digunakan kembali untuk aplikasi analitis.

Fabric Apps adalah aplikasi web standar, jadi Anda dapat mengimplementasikan fitur di luar pola ini. Fitur yang tidak termasuk dalam template mungkin memerlukan rekayasa dan validasi khusus yang lebih lanjut.

Visuals

Template ini mencakup penyorotan silang dan primitif yang telah dikonfigurasi sebelumnya untuk:

Diagram batang, termasuk tata letak vertikal, horizontal, kelompok, dan bertumpuk.
Grafik garis dengan penanda opsional.
Grafik area.
Grafik sebaran.
Grafik pai dan donat.
Heatmaps.
Diagram gelembung.
Peta air terjun.
Kartu nilai tunggal untuk panggilan KPI.
Visual berlapis dan gabungan, seperti diagram batang dengan label data dan grafik garis dengan dua sumbu.

Gunakan bidang dan ukuran yang ada dalam model semantik terhubung. Jangan gantikan kueri konektor yang gagal dengan data tiruan.

Anda bisa meminta agen coding Anda untuk menghasilkan visual lain. Visual tanpa template primitif mungkin memerlukan lebih banyak iterasi dan validasi.

Kemampuan kisi data

Template ini mencakup grid data dengan kemampuan yang telah dikonfigurasi sebelumnya berikut:

Header kolom yang berasal dari metadata model semantik.
Pemformatan angka dan tanggal diterapkan untuk setiap kolom melalui string format.
Penyortiran.
Baris yang dapat digulir dengan penanganan overflow.
Dukungan tema terang dan gelap.
Renderer sel khusus untuk:
- Bilah data untuk nilai numerik.
- Indikator Boolean.
- URL yang dapat diklik.
- Sel gambar dengan hamparan lightbox.
- Sel multi-bidang, seperti nama dan peran dalam satu kolom.

Anda bisa menambahkan kemampuan grid data lain, tapi mungkin memerlukan rekayasa khusus yang lebih banyak.

Pengaturan Tema

Berikan persyaratan branding atau gaya visual untuk agen pemrograman Anda, seperti palet warna, gaya sudut, atau jenis huruf. Templat ini menyimpan gaya bersama di satu lokasi terpusat sehingga setiap perubahan diterapkan ke kartu, tombol, grafik, grid data, dan tooltip.

Styling terpusat menghindari warna yang tidak cocok, font yang tidak konsisten, dan perbedaan tata letak yang dapat terjadi ketika setiap komponen ditata secara terpisah.

Format String

Tentukan format sekali per kolom hasil. Template dapat menggunakan ulang string format model semantik di seluruh sumbu grafik, tooltip, label data, kartu, dan sel grid data.

Misalnya, satu definisi format memastikan 1500.5 ditampilkan sebagai 0.25 dan $1,500.50 ditampilkan sebagai 25% di mana pun nilai tersebut muncul.

Validasi browser

Sebelum Anda mempublikasikan aplikasi, gunakan alur kerja validasi browser Playwright yang disertakan untuk membukanya di browser nyata dan centang:

Elemen visual ditampilkan dengan benar.
Grafik tidak dipotong atau dikompresi.
Teks dapat dibaca.
Tabel data menangani konten yang melebihi batas.
Kondisi memuat, kosong, dan error mudah digunakan.
Filter, cross-highlighting, dan format data bekerja sesuai harapan.
Konsol browser tidak mengalami kesalahan tak terduga.

Alur kerja ini menangkap masalah tata letak dan rendering sebelum pengguna melihatnya. Validasi browser mengonfirmasi perilaku frontend. Uji konektor yang telah diterapkan secara terpisah dengan seorang pengguna yang memiliki akses ke aplikasi Fabric dan model semantik.

Sebarkan dan verifikasi aplikasi

Terapkan aplikasi dan konfigurasi konektor:

npx rayfin up

Buka aplikasi yang telah dideploy dari portal Fabric. Masuk, jalankan setiap interaksi pengguna, dan bandingkan hasil penting dengan model semantik.

Jika sebuah kueri gagal:

Konfirmasi ID item workspace dan model semantik di rayfin.yml.
Pastikan pengaturan penyewa untuk REST API Jalankan Kueri Model Semantik telah diaktifkan.
Konfirmasi pengguna memiliki izin Build dan Read pada model semantik.
Pastikan DAX merujuk pada tabel, kolom, dan ukuran yang sudah ada.
Periksa kategori kesalahan dan pesan hasil konektor.
Periksa konsol browser untuk kesalahan di sisi klien.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-09-29