光环标志
光环基地文档
文档›Edge Functions›Invoke a function

调用函数

如何使用 JavaScript SDK 或通过 HTTP 调用已部署的函数，以及您的函数如何知道谁在调用。

8分钟 读取·级别 中间·修改于 2026年10月12日
该英文文本是根据法文原文自动生成的，尚未经过审查。
该页面已自动翻译。英文版具有权威性。
#
软件开发工具包

1. SDK调用

invoke 是公钥可以进行的唯一调用。它在浏览器和服务器上的工作方式相同。

src/lib/call.tstypescript
import { createClient } from '@aurabase/aurabase-js'

const aura = createClient(process.env.AURA_URL!, process.env.AURA_ANON_KEY!)

const { data, error } = await aura.functions.invoke<{ greeting: string }>('hello', {
  body: { name: 'Ada' },
})
if (error) throw error
console.log(data?.greeting)
src/lib/call-as-user.tstypescript
// 登录后，SDK 会将用户的 JWT 添加到每次调用中：无需额外代码。
await aura.auth.signInWithPassword({ email, password })
const { data } = await aura.functions.invoke('whoami')
// 该函数会看到 x-aura-role: 已验证和用户的 ID。

通用 invoke<T> 仅键入响应。编译时不会检查名称和主体。

公钥只能调用

list、 get、 listJobs、 enqueueJob 和其他管理方法需要 service_role 密钥并且属于您的服务器。公钥接收 403。请参阅 谁可以调用。

#
请求

2. 描述请求

您的函数接收 与您描述的请求完全相同 ，而不是它的包装器。

选项默认该函数看到什么
methodPOSTreq.method
path/new URL(req.url).pathname
headers无req.headers，下面列出的平台标头除外
body无await req.json() （或 req.text() 对于字符串）
timeout客户端默认（30 秒）不可见：取消您的呼叫
signal无不可见：取消您的呼叫
responseType'json'不可见：SDK 如何解码响应，请参阅 非 JSON 响应
request.tstypescript
await aura.functions.invoke('items', {
  method: 'PUT',
  path: '/items/1',
  headers: { 'x-source': 'dashboard' },
  body: { qty: 2 },
})
aurabase/functions/items/index.tstypescript
Deno.serve(async (req) => {
  const url = new URL(req.url)          // 路径名：'/items/1'
  const source = req.headers.get('x-source') // “仪表板”
  const body = await req.json()         // { 数量：2 }
  return Response.json({ method: req.method, id: url.pathname.split('/').pop(), source, body })
})

值得了解的规则：

  • GET 和 HEAD 不带正文发送。
  • 非字符串的正文将作为 JSON 发送，并带有 content-type: application/json ，除非您设置了该值。 字符串 正文按原样发送，并且还会获取 content-type: application/json，因此请使用 req.text()读取它。
  • 如果没有 body，该函数会收到没有正文的请求。裸露的 await req.json() 会抛出异常，因此当可以在没有有效负载的情况下进行调用时，请编写 await req.json().catch(() => ({})) 。
  • 主体必须是 JSON：对象、数组、字符串、数字或布尔值。在发送任何请求之前，会拒绝 Blob、 ArrayBuffer、类型化数组、 FormData、 URLSearchParams 或 ReadableStream ，并显示错误代码 invalid_body 。
  • 帧标头（content-length、 transfer-encoding、 connection、 host等）将被忽略。
#
身份

3.读取来电者身份

平台会在函数运行之前验证密钥和用户的令牌，然后添加以下标头：

标头价值
x-aura-roleanon、 authenticated 或 service_role
x-aura-user-id当 x-aura-role 为 authenticated时用户的 id，否则不存在
x-aura-project-id项目编号
authorization用户的 JWT，仅适用于登录用户
apikey通话时使用的密钥
aurabase/functions/whoami/index.tstypescript
Deno.serve((req) => {
  if (req.headers.get('x-aura-role') !== 'authenticated') {
    return new Response('Sign in first', { status: 401 })
  }
  return Response.json({ userId: req.headers.get('x-aura-user-id') })
})

使用三个不同的键进行此调用的实际结果：

results.jsonjson
{ "role": "anon",          "userId": null }
{ "role": "authenticated", "userId": "b125f8cd-ddc8-4042-9d9d-2e0aa3cebe51" }
{ "role": "service_role",  "userId": null }
调用者无法伪造这些标头

平台会丢弃 authorization、 apikey、 x-request-id 以及调用者放入 headers中的每个 x-aura-* 标头，无论其情况如何。只有它本身验证的值才能达到您的功能。其他自定义标头不变地通过。

函数内没有请求 ID

调用的 x-request-id 不会转发到您的函数。要将调用与日志行关联起来，请生成您自己的 ID，将其发送到 headers 并将其记录到函数中。

#
HTTP协议

4.通过HTTP调用

如果没有 SDK，请发送描述请求的 JSON 对象。 body 字段是您的函数接收的内容。

terminalbash
curl -X POST "$AURA_URL/v1/functions/hello/invoke" \
  -H "apikey: $AURA_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":{"name":"Ada"}}'

apikey 和 Content-Type: application/json 都是必需的。添加 Authorization: Bearer <user JWT> 以作为登录用户进行调用。默认响应是一个信封； X-Aurabase-Invoke-Mode: raw 标头返回函数自己的响应，请参阅 非 JSON 响应。

#
结果

5. 读取结果

invoke 永远不会抛出异常。它返回 { data, error }：

result.tstypescript
const { data, error } = await aura.functions.invoke('hello', { body: { name: 'Ada' } })

if (error) {
  // error.status：失败的 HTTP 状态
  // error.message：函数返回的文本，或平台的解释
  return
}
// 当函数没有返回内容时，数据为 null（例如 204）
if (data === null) return
console.log(data)

当您需要值时测试 data 而不是 error ： TypeScript 然后知道它不是 null。要精确处理故障，请阅读 错误、超时和重试。

最后更新· 2026年10月12日