Rayfin CLI を使用してFabric アプリを作成する

このチュートリアルでは、Rayfin CLI を使用してプロジェクトを作成し、ローカルで実行し、Fabricにデプロイする方法について説明します。 新しいアプリと、後でスキーマまたはフロントエンドを更新する場合にも、同じ CLI ワークフローを使用します。

このチュートリアルでは、次の操作を行います。

  • テンプレートから Fabric Apps プロジェクトを作成します。
  • アプリをローカルで起動します。
  • CLI からFabricにサインインします。
  • Fabric ワークスペースにアプリをデプロイします。
  • デプロイの状態を確認します。

前提条件

  • Fabricへのアクセス。
  • 共同作成者、メンバー、または管理者のアクセス許可を持つFabric ワークスペース。
  • Node.js と npm がインストールされています。

AIプロンプト付きのアプリを作成する

以下のプロンプトを使って、GitHub Copilotまたは他のコーディングエージェントを使って、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

スキャフォールドコマンドは、非インタラクティブ実行のためのプロジェクト名とテンプレートを提供します。 エージェントは残りのワークスペースやデプロイメントの設定の入力を求めることができます。 展開前に生成されたファイルとコマンド出力を確認しましょう。

CLIから新しいアプリを作成する

テンプレートから新しいアプリをスキャフォールディングするには、 npm createを使用します。

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

デフォルトの blankapp テンプレートは Universal App になります。 rayfin/のバックエンド構成、packages/frontend/のフロントエンドコード、packages/data/のランタイムデータ定義、packages/shared/の共有契約を含む新しいnpmワークスペースを作成します。 データはあなたがオプトインするまで無効です。

プロジェクト ディレクトリに移動します。

cd my-app

ヒント

既に空のプロジェクト フォルダーまたは既存のソース コードがある場合は、npx rayfin initではなくnpm createを使用します。

npx rayfin init .

生成されたプロジェクトをレビューしてください

スキャフォールディング後、プロジェクトには、開発を開始するために必要なファイルが含まれます。

  • rayfin/rayfin.yml アプリサービスと展開設定を保存します。
  • rayfin/.env CLIで使用される環境値を格納します。
  • packages/frontend/ UIとフロントエンドビルドが含まれています。
  • packages/data/ ランタイムエンティティクラスとスキーマ登録を含みます。
  • packages/shared/ は、クライアント向けレコードおよびスキーマ コントラクトを含みます。

必要に応じて永続化アプリデータを有効にする:

npm run pack:add -- data-modeling

この機能により Data が有効になり、スターター データや共有定義が追加されます。 ファイルを追加する前に services.data.path と services.staticHosting.path を必ず rayfin/rayfin.yml で確認してください。 他のテンプレートはフラットルート src/ と rayfin/data/ レイアウトを使うこともできますが、それらは代替案であり、デフォルトのUniversal Appレイアウトではありません。

CLIはアクティブなデプロイ値を rayfin/.env に保持し、デプロイを rayfin/.deployments.json に記録します。 パブリック RAYFIN_PUBLIC_* 値はフロントエンドの生成 .env.local にマッピングされ、デプロイせずに再生成するには npx rayfin env --framework vite を使用します。

ファイルごとの詳細な内訳については、「 プロジェクト構造の理解」を参照してください。

アプリをローカルで実行する

ローカル開発環境を開始します。

npx rayfin dev

このコマンドは、スキャフォールディングされたアプリのフロントエンド開発サーバーを起動し、バックエンドをFabricにデプロイします。 アプリが正しく起動することを確認するには、ターミナルに表示されているローカル URL を開きます。

アプリをFabricにデプロイしてください

アプリケーションにさらに多くの機能を組み込みます。 変更をテストした後、もう一度Fabricにデプロイします。

npx rayfin up

変更を加えずにデプロイをプレビューするには、次を実行します。

npx rayfin up --dry-run

デプロイメントを確認する

現在のデプロイ状態を確認します。

npx rayfin up status

マシンが読み取り可能な応答の場合は、JSON 出力を使用します。

npx rayfin up status --json

デプロイが正常に完了すると、CLI によって、デプロイされたアイテムのホストされているアプリの URL とFabric ポータルのリンクが出力されます。

データベースまたは静的コンテンツのみを展開してください

データ モデルのみを変更した場合は、完全な再デプロイなしでデータベースの変更を適用します。

npx rayfin up db apply

フロントエンド コードのみを変更した場合は、静的資産を再デプロイします。

npx rayfin up staticapp deploy

関数の追加

関数はFabricアプリ内のサーバー上で動作するTypeScript関数です。 ブラウザ上で実行してはならないロジック、たとえばシークレットの処理、特権データへのアクセス、アプリのIDを使用した外部サービスの呼び出しには、関数を使用してください。

npx rayfin functions init

イニシャライザーは設定時に services.functions.path を使用し、packages/functions のようなワークスペースの場所を検出したり、既存のフラット rayfin/functions パッケージを保持したりします。 --path <relative-path>を使って場所を明確に選びましょう。

有効化された機能には services.functions.auth.type: application が必要です。 ctx.Tokens.*を通じた外部呼び出しは、アプリのIDとその権限を使用し、呼び出し元ユーザーの外部リソース権限ではありません。 現在のFabricアプリでは、そのアイデンティティがアプリのアイテム所有者です。 各リソースへのアクセスを許可してください。 対照的に、 ctx.getDataClient() は呼び出しのRayfinトークンを使用し、呼び出し元のデータポリシーを保持します。

GitHub Copilotは必要なファイルやコンポーネントの生成と更新が可能です。 また、エージェントにアプリの実行、ローカルでのデバッグ、デプロイを依頼することもできます。 例えば、次のプロンプトを使って、関数を使ってAIプルリクエストレビューアシスタントを作成できます。

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().

ID やデプロイの詳細については、Functions を使用するおよびFunctions を外部リソースに接続するを参照してください。

一般的な問題のトラブルシューティング

サインインに失敗するか、デプロイで 401 または 403 が返される

npx rayfin loginをもう一度実行してから、npx rayfin up再試行してください。

CLI で何が行われるかを調べる必要がある

変更をデプロイする前に、 npx rayfin up --dry-runを実行します。

アプリはデプロイされますが、スキーマのみを変更します

スキーマの変更を個別にプッシュするには、 npx rayfin up db applyを使用します。 列の型の変更や列の削除などの破壊的変更を実行すると、このコマンドは失敗します。 変更を強制するには、 --force フラグを使用します。 このアクションは重大な変更になる可能性があります。

次のステップ