Usar funciones en aplicaciones de Fabric

Las funciones son funciones TypeScript que se ejecutan en el servidor dentro de tu aplicación Fabric. Utiliza funciones lógicas que no deben ejecutarse en el navegador, como trabajar con secretos, acceder a datos privilegiados y llamar a servicios posteriores con la identidad de la app.

Cada función se registra con un nombre y se expone como un punto final HTTP llamable. Tu frontend de React llama a la función a través del cliente tipado de Rayfin, así que no necesitas implementar peticiones, enrutamiento ni manejo de tokens.

Nota:

Los comandos de este artículo utilizan una versión previa de la CLI de Rayfin.

Cuándo usar una función

Utiliza una función Rayfin para:

  • Llama a una API externa con un token de aplicación. Ejemplos incluyen Fundición de IA de Azure, Azure DevOps, Fabric, Azure Storage y Azure Key Vault.
  • Lee o escribe la base de datos de la app con seguridad a nivel de fila impuesta por el servidor.
  • Mantén las claves de API, los nombres de despliegue de los modelos y otros secretos fuera del código del cliente.
  • Ejecuta la orquestación, como llamadas en abanico, agregación o indicaciones para IA, cerca de los datos.

Prerequisites

Antes de empezar, instala o crea los siguientes recursos:

  • Node.js 20 o más tarde y npm.
  • Un andamiaje de la app Fabric creado con la CLI de Rayfin.
  • Azure Functions Core Tools, que utiliza el host local de funciones para depuración.

Instalar Azure Functions Core Tools versión 4:

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

Crea una app con funciones

Estructura una aplicación e inicializa sus funciones proyecto:

npm create @microsoft/rayfin@latest

cd my-app

npx rayfin functions init

El rayfin functions init comando añade el proyecto de funciones, su configuración en TypeScript y un archivo de función inicial a la aplicación existente.

Construye la app con GitHub Copilot

El andamiaje incluye las instrucciones y habilidades de GitHub Copilot necesarias para trabajar con el proyecto. Abre el proyecto en Visual Studio Code y describe la aplicación que quieres crear en GitHub Copilot Chat.

Por ejemplo, utiliza el siguiente prompt para crear un asistente de revisión de pull requests 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 puede generar y actualizar los archivos y componentes necesarios. También puedes pedirle al agente que ejecute la app, depure funciones localmente y despliegue la app.

Entiende la disposición del proyecto

El comando de inicialización de funciones actualiza rayfin/rayfin.yml y crea rayfin/functions. Una aplicación típica con funciones tiene la siguiente estructura:

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

Los archivos cumplen los siguientes propósitos:

Camino propósito
rayfin/rayfin.yml Configura la autenticación, datos, funciones y servicios de alojamiento estático.
rayfin/data/ Contiene los modelos de datos y exportaciones de esquemas de la app.
rayfin/functions/package.json Define las dependencias y los scripts de compilación para el proyecto de funciones.
rayfin/functions/tsconfig.json Configura la compilación de TypeScript para funciones.
rayfin/functions/src/function_app.ts Contiene tus implementaciones de funciones.
rayfin/functions/src/types.ts Contiene los tipos AppFunctionsSchema generados. No edite este archivo manualmente.
src/ Contiene el frontend React y cualquier tipo de dominio o envoltorio compartido.

Cuando activas funciones, rayfin/rayfin.yml incluye el servicio de funciones:

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

Autenticación de aplicaciones

Las Funciones Habilitadas requieren autenticación explícita de la aplicación en rayfin/rayfin.yml:

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

Nuevo conjunto de plantillas de Functions auth.type: application.

Las funciones deshabilitadas pueden omitir auth. Sin embargo, si suministras auth, debe incluir:

auth:
  type: application

Un flujo completo npx rayfin up y el flujo normal npx rayfin dev validan esta configuración antes de aplicar configuraciones del proyecto tanto al backend de Fabric como de Docker.

Ejecuta una npx rayfin up completa para aplicar el modo de autenticación YAML a una aplicación remota existente.

Rutas de autenticación utilizadas por las funciones desplegadas

Las Funciones Desplegadas utilizan dos rutas de autenticación separadas:

Ruta de acceso Credencial Identidad y permisos
Conexiones externas a través ctx.Tokens.* Token de recurso proporcionado por la plataforma Identidad de la aplicación y sus permisos sobre el recurso externo
Rayfin DB hasta ctx.getDataClient() el token Rayfin de Invocation Identidad del llamante y permisos en la base de datos Rayfin

Para las aplicaciones Fabric actuales, la identidad de la aplicación es el propietario del elemento BaaS.

Por tanto, las conexiones externas utilizan los permisos del propietario del elemento, no los permisos del usuario de la aplicación que invoca la función. Concede a la identidad de la app los permisos requeridos por cada recurso externo y API llamada por el código de Funciones.

Declarar una audiencia o desplegar Funciones no otorga permisos de identidad a la app a un recurso externo.

El inicio de sesión en la app y la autorización para invocar una función son independientes del acceso de la identidad de la app a recursos externos.

El acceso a la base de datos Rayfin siempre utiliza el token Rayfin y preserva la identidad del llamante y los permisos de la base de datos. La configuración services.functions.auth.type: application no cambia el acceso a la base de datos Rayfin a la identidad de la aplicación.

Para declaraciones de audiencia, tokens de recursos, permisos y comportamiento de desarrollo local, consulte Conectar Funciones a recursos externos.

Ejecución local de la aplicación

Desde la carpeta raíz de la app, inicia sesión:

cd my-app
npx rayfin login

Inicia el frontend y el host local de funciones:

npm run dev

En un proyecto habilitado por funciones, npm run dev se mapea a rayfin dev. Este comando aplica el esquema, inicia el host de funciones locales y pone en marcha el servidor de desarrollo Vite. Abre la URL local impresa en el terminal y mantén el terminal activo mientras desarrollas y depuras la aplicación.

Para iniciar solo el anfitrión de funciones, por ejemplo, cuando ejecutas la interfaz por separado, usa el siguiente comando:

cd my-app
npx rayfin dev

Implementar en Fabric

Despliega los datos, el sitio estático y las funciones de la app:


npx rayfin up --workspace <workspace-name>

Sustituye <WORKSPACE> por el nombre del espacio de trabajo de Fabric de destino.

Añadir funciones a una aplicación existente

Desde la raíz de una aplicación Fabric existente, activa la función e inicializa el proyecto de funciones una vez:


npx rayfin functions init

Tras la inicialización, añadir implementaciones de funciones a rayfin/functions/src/function_app.ts.

Limitations

  • Propiedad de la función: Solo el propietario del elemento de funciones de datos de usuario puede modificar y publicar el código de las funciones.
  • Tiempo de recarga para publicar: Espera al menos dos minutos después de publicar antes de volver a publicar. Este periodo de espera se aplica al publicar desde el portal de Functions en el navegador, la extensión de Visual Studio Code para funciones de datos de usuario, la acción de importación de Git o las canalizaciones de implementación.
  • Tamaño del paquete de despliegue: El archivo ZIP de Funciones no puede superar los 30 MB.
  • Tamaño de la carga útil de la solicitud: El servicio de funciones de datos de usuario documenta un máximo de 4 MB para todos los parámetros de solicitud combinados. Se espera que este límite se aplique a Rayfin Functions, pero no se ha verificado.
  • Tiempo de ejecución: Una función puede ejecutarse hasta 240 segundos.
  • Retención de registros de invocaciones: Los registros históricos de invocación se conservan por defecto durante 30 días.
  • Identidad de la aplicación: La identidad de la aplicación es actualmente el propietario del elemento BaaS.

Para los requisitos regionales de disponibilidad y más detalles sobre las limitaciones de las funciones de datos de usuario, consulte Detalles y limitaciones del servicio de las funciones de datos de usuario de Fabric.

Contenido relacionado

  • Última actualización el