Usa le funzioni nelle app Fabric

Le funzioni sono funzioni TypeScript che girano sul server all'interno della tua app Fabric. Usa funzioni logiche che non devono essere eseguite nel browser, come lavorare con i segreti, accedere ai dati privilegiati e chiamare servizi a valle con l'identità dell'app.

Ogni funzione viene registrata con un nome ed esposta come endpoint HTTP richiamabile. Il tuo frontend React chiama la funzione tramite il client Rayfin tipizzato, quindi non devi implementare richieste, routing o gestione dei token.

Annotazioni

I comandi in questo articolo utilizzano una versione anteprima della CLI di Rayfin.

Quando usare una funzione

Usa una funzione Rayfin per:

  • Chiama un'API esterna con un token applicativo. Esempi includono Azure AI Foundry, Azure DevOps, Fabric, Archiviazione di Azure e Azure Key Vault.
  • Leggi o scrivi il database dell'app con la sicurezza a livello di riga imposta dal server.
  • Tieni le chiavi API, i nomi dei modelli di distribuzione e altri segreti fuori dal codice client.
  • Esegui processi di orchestrazione, come chiamate fan-out, aggregazione o prompting dell'IA, vicino ai dati.

Prerequisiti

Prima di iniziare, installa o crea le seguenti risorse:

  • Node.js 20 o versione successiva e npm.
  • Una struttura di base per l'app Fabric creata con la CLI Rayfin.
  • Funzioni di Azure Core Tools, che l'host delle funzioni locali utilizza per il debug.

Installa Funzioni di Azure Core Tools versione 4:

npm install --global azure-functions-core-tools@4

Crea un'app con funzioni

Crea la struttura di un'app e inizializza il relativo progetto Functions:

npm create @microsoft/rayfin@latest

cd my-app

npx rayfin functions init

Il rayfin functions init comando aggiunge il progetto funzioni, la configurazione TypeScript e un file funzione starter all'app esistente.

Costruisci l'app con GitHub Copilot

La struttura include le istruzioni di GitHub Copilot e le competenze necessarie per lavorare al progetto. Apri il progetto in Visual Studio Code e descrivi l'app che vuoi costruire su GitHub Copilot Chat.

Ad esempio, usa il seguente prompt per costruire un assistente di revisione pull request con IA:

Build an app that helps business analysts track sales performance across
regions. Show key metrics, let analysts ask questions about trends, and
use Functions to securely retrieve data from our sales API with application
authentication.

GitHub Copilot può generare e aggiornare i file e i componenti necessari. Puoi anche chiedere all'agente di eseguire l'app, debugare le funzioni localmente e distribuire l'app.

Comprendere la disposizione del progetto

Il comando di inizializzazione di Functions aggiorna rayfin/rayfin.yml e crea rayfin/functions. Un'app tipica con funzioni ha la seguente struttura:

my-app/
├── rayfin/
│   ├── rayfin.yml
│   ├── data/
│   │   ├── TripPlan.ts
│   │   └── schema.ts
│   └── functions/
│       ├── package.json
│       ├── tsconfig.json
│       └── src/
│           ├── function_app.ts
│           └── types.ts
└── src/
    └── services/

I file servono ai seguenti scopi:

Percorso Purpose
rayfin/rayfin.yml Configura autenticazione, dati, funzioni e servizi di hosting statico.
rayfin/data/ Contiene i modelli dati dell'app e le esportazioni degli schemi.
rayfin/functions/package.json Definisce le dipendenze e compila script per il progetto funzioni.
rayfin/functions/tsconfig.json Configura la build TypeScript per le funzioni.
rayfin/functions/src/function_app.ts Contiene le tue implementazioni funzionali.
rayfin/functions/src/types.ts Contiene i tipi AppFunctionsSchema generati. Non modificare il file manualmente.
src/ Contiene il frontend React e qualsiasi tipo di dominio condiviso o wrapper.

Quando abiliti funzioni, rayfin/rayfin.yml include il servizio funzioni:

services:
  functions:
    enabled: true
    auth:
      type: application
    buildCommand: npm run build

Autenticazione dell'applicazione

Le funzioni abilitate richiedono un'autenticazione esplicita dell'applicazione in rayfin/rayfin.yml:

services:
  functions:
    enabled: true
    auth:
      type: application
    buildCommand: npm run build

Nuove Funzioni impalcatura impostano auth.type: application.

Le funzioni disabilitate possono omettere auth. Tuttavia, se fornisci auth, deve includere:

auth:
  type: application

Un flow completo npx rayfin up e quello normale npx rayfin dev validano questa impostazione prima di applicare le impostazioni del progetto sia al backend Fabric che Docker.

Esegui una npx rayfin up completa per applicare la modalità di autenticazione YAML a un'applicazione remota esistente.

Percorsi di autenticazione utilizzati dalle Funzioni distribuite

Le Funzioni Distribuite utilizzano due percorsi di autenticazione separati:

Percorso di accesso Credential Identità e autorizzazioni
Collegamenti esterni attraverso ctx.Tokens.* Token di risorsa fornito dalla piattaforma Identità dell'applicazione e i suoi permessi sulla risorsa esterna
Rayfin DB tramite ctx.getDataClient() Il gettone Rayfin di Invocazione Identità del chiamante e permessi sul database Rayfin

Per le attuali app Fabric, l'identità dell'applicazione è il proprietario dell'elemento BaaS.

Le connessioni esterne quindi utilizzano i permessi del proprietario dell'oggetto, non quelli dell'utente dell'app che invoca la funzione. Concedere all'identità dell'app i permessi richiesti da ogni risorsa esterna e API chiamata dal codice delle Funzioni.

La dichiarazione di destinatari o la distribuzione di Functions non concede all'identità dell'app le autorizzazioni necessarie per accedere a una risorsa esterna.

L'accesso all'app e l'autorizzazione a invocare una funzione sono separati dall'accesso dell'identità dell'app alle risorse esterne.

L'accesso al database Rayfin utilizza sempre il token Rayfin e preserva l'identità del chiamante e i permessi del database. L'impostazione services.functions.auth.type: application non cambia l'accesso al database Rayfin all'identità dell'applicazione.

Per informazioni su dichiarazioni dei destinatari, token delle risorse, autorizzazioni e comportamento in fase di sviluppo locale, vedere Connettere Functions a risorse esterne.

Eseguire l'applicazione localmente

Dalla cartella principale dell'app, accedi:

cd my-app
npx rayfin login

Avvia il frontend e l'host locale delle funzioni:

npm run dev

In un progetto con funzioni abilitate, npm run dev corrisponde a rayfin dev. Questo comando applica lo schema, avvia l'host delle funzioni locali e avvia il server di sviluppo Vite. Apri l'URL locale stampato nel terminale e tieni il terminale attivo mentre sviluppi e fai il debug dell'app.

Per avviare solo l'host delle funzioni, ad esempio quando esegui il frontend separatamente, usa invece il seguente comando:

cd my-app
npx rayfin dev

Eseguire la distribuzione in Fabric

Distribuisci i dati dell'app, il sito statico e le funzioni:


npx rayfin up --workspace <workspace-name>

Sostituisci <WORKSPACE> con il nome dello spazio di lavoro Fabric di destinazione.

Aggiungi funzioni a un'app esistente

Dalla radice di un'app Fabric esistente, abilita la funzionalità e inizializza il progetto delle funzioni una volta:


npx rayfin functions init

Dopo l'inizializzazione, aggiungere le implementazioni di funzioni a rayfin/functions/src/function_app.ts.

Limitations

  • Proprietà delle funzioni: Solo il proprietario dell'elemento funzione dati utente può modificare e pubblicare il codice delle funzioni.
  • Cooldown per la pubblicazione: Aspetta almeno due minuti dopo aver pubblicato prima di pubblicare di nuovo. Questo periodo di attesa si applica quando si pubblica dal portale di Functions nel browser, dall'estensione di Visual Studio Code per User Data Functions, dall'azione Importa da Git o dalle pipeline di distribuzione.
  • Dimensione del pacchetto di distribuzione: Il file ZIP Functions non può superare i 30 MB.
  • Dimensione del payload della richiesta: il servizio delle funzioni dati utente documenta un massimo di 4 MB per tutti i parametri della richiesta combinati. Questo limite dovrebbe applicarsi alle funzioni Rayfin, ma non è stato verificato.
  • Timeout di esecuzione: una funzione può funzionare fino a 240 secondi.
  • Conservazione dei registri delle invocazioni: I registri storici delle invocazioni vengono conservati per 30 giorni di default.
  • Identità dell'applicazione: L'identità dell'applicazione è attualmente proprietaria dell'elemento BaaS.

Per i requisiti di disponibilità regionale e maggiori dettagli sulle limitazioni delle funzioni dati utente, vedi Dettagli e limitazioni dei servizi delle funzioni dati utente Fabric.

Contenuti correlati

  • Ultimo aggiornamento: