用途
Rayfin Functions 用于编写运行在 Fabric 运行时中的服务端用户自定义函数(UDF),编写一次可信后端逻辑,即可在前端获得类型安全的客户端调用。适用于需要从 Rayfin 前端调用后端函数、访问数据实体、读取密钥或连接外部资源的场景。
主要能力
- UDF 编写:通过
udf.func()API、RayfinContext实现数据访问与实体导入,相关文档位于functions/writing-functions.md。 - 类型生成:
types.ts由 typegen 自动生成并保持同步,文档位于functions/typegen.md。 - 密钥读取:使用
rayfin secret set声明密钥,记录在rayfin.yml,通过ctx.Secrets.STRIPE_API_KEY形式读取;CLI 生成rayfin/functions/src/secrets.generated.ts。 - 前端调用:通过
client.functions.*.invoke调用函数,文档位于functions/invoking-from-frontend.md。 - 外部连接:支持 Sql、Storage、Fabric、AzureAI、ADO 受众;在上下文注解上声明,读取为
ctx.Tokens.Sql,注解即注册绑定,udf.func()第三个参数保持[]。 - CLI:提供 scaffold、本地主机、dev-apply、deploy 等命令。
使用方式
- 优先按任务阅读对应文档:可从
node_modules/@microsoft/rayfin-guide/assets/docs/<path>读取,或用rayfin docs get --module guide --path '<path>',或通过 MCP 使用get_doc(module: "guide")。 - 启用 Functions 需配置
services.functions.auth.type: application。 - 编写连接代码前阅读
functions/connections/index.md,读取密钥前阅读functions/secrets.md。 - 连接外部资源需真实端点(SQL 服务器或 OneLake 路径),应自行解析而非要求用户粘贴连接字符串;可优先使用可用的 Fabric CLI 或 Fabric MCP,否则直接调用 Fabric REST API(
https://api.fabric.microsoft.com/v1)。 - 本地开发:内置 Vite 模板已使用
@microsoft/rayfin-local-dev的rayfinLocalDev(),保持functionsBaseUrl未定义,SDK 使用/functions/<name>/invoke,由适配器转发到rayfin dev选定的本地 Functions 主机。
限制与约束
- 从
@microsoft/fabric-user-data-functions导入RayfinContext,而非从@microsoft/rayfin-functions。 - 每个函数必须用
udf.func(name, handler, [])注册,不要导出裸函数。 - 数据实体使用
import type导入。 - 不得手工编辑
rayfin/functions/src/types.ts。 - 生产环境不得暴露本地 Functions URL。
- 资源 SDK 包安装在
rayfin/functions/package.json,而非项目根目录。 ctx.getToken()与ctx.getSecret()已弃用,应使用ctx.Tokens与ctx.Secrets。- 受众在部署时由 TypeScript 编译器解析,建议在 functions 项目中保留
tsconfig.json。 - 资料未提供定价、平台支持范围及性能数据。