SuperAPI AI 工具集

rayfin-functions

编程与开发

查看项目

更新于 11-09 23:01

技能介绍

用途

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。
  • 资料未提供定价、平台支持范围及性能数据。