Membuat aplikasi Fabric dengan Rayfin CLI

Tutorial ini menunjukkan kepada Anda cara menggunakan Rayfin CLI untuk membuat proyek, menjalankannya secara lokal, dan menyebarkannya ke Fabric. Anda menggunakan alur kerja CLI yang sama untuk aplikasi baru dan untuk pembaruan nanti pada skema atau frontend Anda.

Di tutorial ini, Anda akan:

  • Buat proyek Fabric Apps dari templat.
  • Mulai aplikasi secara lokal.
  • Masuk ke Fabric dari CLI.
  • Sebarkan aplikasi ke ruang kerja Fabric.
  • Verifikasi status penyebaran.

Prasyarat

  • Akses ke Fabric.
  • Ruang kerja Fabric tempat Anda memiliki izin Kontributor, Anggota, atau Admin.
  • Fitur Fabric Apps yang diaktifkan di tenant Anda
  • Node.js dan npm terinstal.

Buat aplikasi dengan prompt AI

Gunakan prompt berikut dengan GitHub Copilot atau agen pengkode lain untuk membuat, menjelajahi, menjalankan, menyesuaikan, dan menyebarkan aplikasi Fabric:

Set up a new Fabric App project called "rayfin-app-ws".

1. Run: npx -y @microsoft/create-rayfin@latest --project-name rayfin-app-ws --template blankapp
2. Open the scaffolded project directory.
3. Explore the project structure and understand the Rayfin app framework.
4. Run: npm run dev
5. Make changes to the app based on my instructions.
6. When ready, deploy with: npx rayfin up

Perintah scaffold menyediakan nama proyek dan template untuk eksekusi noninteraktif. Agen dapat meminta pengaturan workspace atau deployment lain yang tersisa. Tinjau file yang dihasilkan dan output perintah sebelum penerapan.

Buat aplikasi baru dari CLI

Untuk membuat aplikasi baru dari templat, gunakan npm create:

npm create @microsoft/rayfin@latest -- my-app --workspace <workspacename>

Template default blankapp diuraikan menjadi Universal App. Ini membuat workspace npm baru dengan konfigurasi backend di rayfin/, kode frontend di packages/frontend/, definisi data runtime di packages/data/, dan kontrak bersama di packages/shared/. Data tidak tersedia sampai Anda memilih ikut serta.

Buka direktori proyek:

cd my-app

Tip

Jika Anda sudah memiliki folder proyek kosong atau kode sumber yang sudah ada, gunakan npx rayfin init alih-alih npm create.

npx rayfin init .

Tinjau proyek yang dihasilkan

Setelah kerangka proyek dibuat, proyek ini mencakup file-file yang Anda perlukan untuk mulai mengembangkan proyek:

  • rayfin/rayfin.yml menyimpan layanan aplikasi dan pengaturan penyebaran.
  • rayfin/.env menyimpan nilai lingkungan yang digunakan oleh CLI.
  • packages/frontend/ berisi build UI dan frontend.
  • packages/data/ Berisi kelas entitas runtime dan registrasi skema.
  • packages/shared/ berisi kontrak rekor dan skema yang ditujukan untuk klien.

Aktifkan data aplikasi yang disimpan saat diperlukan:

npm run pack:add -- data-modeling

Kemampuan ini mengaktifkan Data dan menambahkan data pemula serta definisi bersama. Cek services.data.path dan services.staticHosting.path di rayfin/rayfin.yml sebelum menambahkan file. Template lain dapat menggunakan tata letak flat root src/ dan rayfin/data/; tata letak tersebut adalah alternatif, bukan tata letak default Universal App.

CLI menjaga nilai deployment aktif di rayfin/.env dan merekam deployment di rayfin/.deployments.json. Nilai publik RAYFIN_PUBLIC_* dipetakan ke dalam frontend yang dihasilkan .env.local; gunakan npx rayfin env --framework vite untuk meregenerasinya tanpa deployment.

Untuk perincian file demi file terperinci, lihat Memahami struktur proyek.

Menjalankan aplikasi secara lokal

Mulai lingkungan pengembangan lokal:

npx rayfin dev

Perintah ini memulai server pengembangan frontend untuk aplikasi perancah dan menyebarkan backend ke Fabric. Untuk mengonfirmasi aplikasi dimulai dengan benar, buka URL lokal yang ditampilkan di terminal.

Sebarkan aplikasi ke Fabric

Bangun lebih banyak fitur ke dalam aplikasi Anda. Setelah Menguji perubahan, sebarkan ke Fabric lagi.

npx rayfin up

Untuk mempratinjau penyebaran tanpa membuat perubahan, jalankan:

npx rayfin up --dry-run

Verifikasi proses penyebaran

Periksa status penyebaran saat ini:

npx rayfin up status

Untuk respons yang dapat dibaca mesin, gunakan output JSON:

npx rayfin up status --json

Setelah penyebaran berhasil, CLI mencetak URL aplikasi yang dihosting dan tautan portal Fabric untuk item yang disebarkan.

Hanya terapkan konten database atau statis

Jika Anda hanya mengubah model data, terapkan perubahan database tanpa penyebaran ulang penuh:

npx rayfin up db apply

Jika Anda hanya mengubah kode frontend, sebarkan ulang aset statis:

npx rayfin up staticapp deploy

Tambah fungsi

Fungsi adalah fungsi TypeScript yang berjalan di server di dalam aplikasi Fabric Anda. Gunakan fungsi untuk logika yang tidak boleh berjalan di browser, seperti bekerja dengan rahasia, mengakses data terproteksi, dan memanggil layanan eksternal dengan identitas aplikasi.

npx rayfin functions init

Inisialisator menggunakan services.functions.path saat dikonfigurasi, mendeteksi lokasi workspace seperti packages/functions, atau mempertahankan paket datar rayfin/functions yang sudah ada. Gunakan --path <relative-path> untuk memilih lokasi secara eksplisit.

Fungsi aktif memerlukan services.functions.auth.type: application. Panggilan eksternal melalui ctx.Tokens.* menggunakan identitas aplikasi dan izinnya, bukan izin sumber daya eksternal pengguna yang memanggil. Dalam aplikasi Fabric saat ini, akun tersebut adalah pemilik item aplikasi. Berikan akses kepadanya ke setiap sumber daya. Sebaliknya, ctx.getDataClient() menggunakan token Rayfin dari invocation dan mempertahankan kebijakan data penelpon.

GitHub Copilot dapat menghasilkan dan memperbarui file serta komponen yang diperlukan. Anda juga dapat meminta agen menjalankan aplikasi, melakukan debug fungsi secara lokal, dan menyebarkan aplikasi. Misalnya, Anda dapat menggunakan prompt berikut untuk membuat asisten AI untuk meninjau pull request menggunakan fungsi:

Build an app that lets me view all pull requests for the repository
<repoURL>, chat with my Azure AI Foundry agent <agentName> to review
pull requests, and post review comments. Use Functions with application
authentication to connect to Azure AI Foundry and Azure DevOps. Grant the
app identity the required resource permissions, and preserve the caller's
Rayfin data policies when using ctx.getDataClient().

Lihat Gunakan Fungsi dan Hubungkan Fungsi ke sumber daya eksternal untuk detail identitas dan deployment.

Mengatasi masalah umum

Proses masuk gagal atau penyebaran mengembalikan 401 atau 403

Jalankan npx rayfin login lagi, lalu coba npx rayfin uplagi .

Anda perlu memeriksa apa yang akan dilakukan CLI

Sebelum menyebarkan perubahan, jalankan npx rayfin up --dry-run.

Aplikasi berhasil di-deploy, tetapi Anda hanya mengubah skema

Untuk mendorong perubahan skema secara independen, gunakan npx rayfin up db apply. Jika Anda melakukan perubahan destruktif seperti mengubah jenis kolom atau menghapus kolom, perintah ini gagal. Untuk memaksa perubahan, Anda dapat menggunakan --force bendera. Tindakan ini bisa menjadi perubahan yang melanggar.

Langkah berikutnya

  • Terakhir diperbarui pada