Créer une application Fabric avec l’interface CLI Rayfin

Ce tutoriel vous montre comment utiliser l’interface CLI Rayfin pour créer un projet, l’exécuter localement et le déployer sur Fabric. Vous utilisez le même flux de travail CLI pour les nouvelles applications et pour les mises à jour ultérieures de votre schéma ou serveur frontal.

Dans ce tutoriel, vous allez :

  • Créez un projet Fabric Apps à partir d’un modèle.
  • Démarrez l’application localement.
  • Connectez-vous à Fabric à partir de l’interface CLI.
  • Déployez l’application sur un espace de travail Fabric.
  • Vérifiez l’état du déploiement.

Prerequisites

  • Accès à Fabric.
  • Un espace de travail Fabric où vous disposez des autorisations Contributeur, Membre ou Administrateur.
  • Charge de travail Fabric Apps activée dans votre tenant.
  • Node.js et npm installés.

Créez une application avec un prompt IA

Utilisez l’invite suivante avec GitHub Copilot ou un autre agent de codage pour créer, explorer, exécuter, personnaliser et déployer une application 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

La commande scaffold fournit le nom du projet et le modèle pour une exécution non interactive. L’agent peut demander les paramètres restants de l’espace de travail ou du déploiement. Examinez les fichiers générés et les commandes générées avant le déploiement.

Créer une nouvelle application à partir de CLI

Pour générer une structure d’une nouvelle application à partir d’un modèle, utilisez npm create:

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

Le modèle par défaut blankapp se résout en Universal App. Il crée un nouvel espace de travail npm avec la configuration backend sous rayfin/, code frontend dans packages/frontend/, définitions de données à l’exécution dans packages/data/, et contrats partagés dans packages/shared/. Les données sont désactivées tant que vous n’avez pas activé.

Accédez au répertoire du projet :

cd my-app

Conseil / Astuce

Si vous disposez déjà d’un dossier de projet vide ou d’un npx rayfin initcode source existant, utilisez npm create plutôt que .

npx rayfin init .

Examinez le projet généré

Après la génération de la structure du projet, le projet inclut les fichiers dont vous avez besoin pour commencer à développer :

  • rayfin/rayfin.yml stocke les services d’application et les paramètres de déploiement.
  • rayfin/.env stocke les valeurs d’environnement utilisées par l’interface CLI.
  • packages/frontend/ contient l’interface utilisateur et le build frontend.
  • packages/data/ contient des classes d’entité d’exécution et l’enregistrement de schéma.
  • packages/shared/ contient des contrats d’enregistrements et de schéma destinés au client.

Activez les données d’application persistantes lorsque cela est nécessaire :

npm run pack:add -- data-modeling

Cette capacité active Data et ajoute des données de départ ainsi que des définitions partagées. Vérifiez services.data.path et services.staticHosting.path dans rayfin/rayfin.yml avant d’ajouter des fichiers. D’autres modèles peuvent utiliser une mise en page à racine plate src/ et rayfin/data/ ; ces mises en page sont des alternatives, pas la mise en page par défaut de l’application universelle.

La CLI conserve les valeurs de déploiement actives dans rayfin/.env et enregistre les déploiements dans rayfin/.deployments.json. Les valeurs publiques RAYFIN_PUBLIC_* sont mappées dans le frontend généré .env.local; utilisez npx rayfin env --framework vite pour le régénérer sans déployer.

Pour obtenir une répartition détaillée des fichiers par fichier, consultez Comprendre la structure du projet.

Exécutez l’application localement.

Démarrez l’environnement de développement local :

npx rayfin dev

Cette commande démarre le serveur de développement du frontend pour l’application générée et déploie le backend sur Fabric. Pour confirmer que l’application démarre correctement, ouvrez l’URL locale affichée dans le terminal.

Déploie l’application sur Fabric

Générez d’autres fonctionnalités dans votre application. Après avoir testé vos modifications, déployez à nouveau sur Fabric.

npx rayfin up

Pour afficher un aperçu du déploiement sans apporter de modifications, exécutez :

npx rayfin up --dry-run

Vérifier le déploiement

Vérifiez l’état actuel du déploiement :

npx rayfin up status

Pour une réponse lisible par l’ordinateur, utilisez la sortie JSON :

npx rayfin up status --json

Une fois le déploiement réussi, l’interface CLI imprime l’URL de l’application hébergée et le lien du portail Fabric pour l’élément déployé.

Déploie uniquement du contenu statique ou de base de données

Si vous avez uniquement modifié des modèles de données, appliquez les modifications de base de données sans redéploiement complet :

npx rayfin up db apply

Si vous avez uniquement modifié le code frontal, redéployez les ressources statiques :

npx rayfin up staticapp deploy

Ajouter des fonctions

Les fonctions sont des fonctions TypeScript qui s’exécutent sur le serveur de votre application Fabric. Utilisez des fonctions dédiées à la logique qui ne doivent pas s’exécuter dans le navigateur, comme travailler avec des secrets, accéder à des données privilégiées et appeler des services externes via l’identité de l’application.

npx rayfin functions init

L’initialiseur utilise services.functions.path lorsqu’il est configuré, détecte un emplacement d’espace de travail tel que packages/functions, ou conserve un paquet plat rayfin/functions existant. Utilisez --path <relative-path> pour choisir explicitement un lieu.

Les fonctions activées nécessitent services.functions.auth.type: application. Les appels externes via ctx.Tokens.* utilisent l’identité de l’application et ses permissions, et non les permissions de ressource externe de l’utilisateur appelant. Dans les applications Fabric actuelles, cette identité est le propriétaire de l’élément d’application. Accordez-lui accès à chaque ressource. En revanche, ctx.getDataClient() utilise le jeton Rayfin de l’invocation et préserve les politiques de données de l’appelant.

GitHub Copilot peut générer et mettre à jour les fichiers et composants requis. Vous pouvez aussi demander à l’agent d’exécuter l’application, de déboguer les fonctions localement, puis de déployer l’application. Par exemple, vous pouvez utiliser l’invite suivante pour créer un assistant de révision des pull requests IA en utilisant des fonctions :

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

Voir Utiliser les fonctions et connecter les fonctions à des ressources externes pour les détails sur l’identité et le déploiement.

Résoudre les problèmes courants

La connexion échoue ou le déploiement retourne 401 ou 403

Réexécutez npx rayfin login , puis réessayez npx rayfin up.

Vous devez examiner ce que la CLI va faire

Avant de déployer des modifications, exécutez npx rayfin up --dry-run.

L’application se déploie, mais vous modifiez le schéma uniquement

Pour envoyer des modifications de schéma indépendamment, utilisez npx rayfin up db apply. Si vous effectuez des modifications destructrices telles que la modification du type d’une colonne ou la suppression d’une colonne, cette commande échoue. Pour forcer vos modifications, vous pouvez utiliser l’indicateur --force . Cette action peut être un changement cassant.

Étapes suivantes

  • Dernière mise à jour :