Logotipo de Aurabase
aurabasedocumentos
documentos›Edge Functions›Invoke a function

Invocar una función

Cómo llamar a una función implementada con el SDK de JavaScript o a través de HTTP, y cómo su función sabe quién está llamando.

8 min leer·Nivel intermedio·Revisado el 12 oct 2026
Este texto en inglés se generó automáticamente a partir del original en francés y aún no ha sido revisado.
Esta página fue traducida automáticamente. La versión en inglés es autorizada.
#
SDK

1. Llamada desde el SDK

invoke es la única llamada que puede realizar una clave pública. Funciona igual en un navegador y en un servidor.

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
// Después de iniciar sesión, el SDK agrega el JWT del usuario a cada llamada: sin código adicional.
await aura.auth.signInWithPassword({ email, password })
const { data } = await aura.functions.invoke('whoami')
// La función ve x-aura-role: autenticado y la identificación del usuario.

El invoke<T> genérico solo escribe la respuesta. El nombre y el cuerpo no se verifican en el momento de la compilación.

Una clave pública sólo puede invocar

list, get, listJobs, enqueueJob y los otros métodos de administración necesitan una clave service_role y pertenecen a su servidor. Una clave pública recibe 403. Vea quién puede llamar a qué.

#
Solicitar

2. Describe la solicitud

Su función recibe exactamente la solicitud que usted describe, no un envoltorio a su alrededor.

OpciónPredeterminadoLo que ve la función
methodPOSTreq.method
path/new URL(req.url).pathname
headersningunoreq.headers, excepto los encabezados de plataforma que se enumeran a continuación
bodyningunoawait req.json() (o req.text() para una cadena)
timeoutvalor predeterminado del cliente (30 s)no visible: cancela tu llamada
signalningunono visible: cancela tu llamada
responseType'json'no visible: cómo el SDK decodifica la respuesta; consulte respuestas que no sean 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)          // nombre de ruta: '/elementos/1'
  const source = req.headers.get('x-source') // 'tablero'
  const body = await req.json()         // {cantidad: 2}
  return Response.json({ method: req.method, id: url.pathname.split('/').pop(), source, body })
})

Reglas que vale la pena conocer:

  • GET y HEAD se envían sin cuerpo.
  • Un cuerpo que no es una cadena se envía como JSON, con content-type: application/json a menos que establezca uno. Un cuerpo de cadena se envía tal cual y también recibe content-type: application/json, así que léelo con req.text().
  • Sin body, la función recibe una solicitud sin cuerpo. Se arroja un await req.json() desnudo, así que escriba await req.json().catch(() => ({})) cuando la llamada se pueda realizar sin una carga útil.
  • El cuerpo debe ser JSON: un objeto, matriz, cadena, número o booleano. Una matriz escrita Blob, ArrayBuffer, FormData, URLSearchParams o ReadableStream se rechaza con el código de error invalid_body antes de enviar cualquier solicitud.
  • Los encabezados de marco (content-length, transfer-encoding, connection, host,…) se ignoran.
#
Identidad

3. Lea la identidad de la persona que llama.

La plataforma valida la clave y el token del usuario antes de que se ejecute la función y luego agrega estos encabezados:

encabezadoValor
x-aura-roleanon, authenticated o service_role
x-aura-user-idLa identificación del usuario cuando x-aura-role es authenticated; de lo contrario, está ausente
x-aura-project-idLa identificación del proyecto
authorizationEl JWT del usuario, solo para un usuario que haya iniciado sesión
apikeyLa clave utilizada para la llamada.
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') })
})

Resultados reales de esta convocatoria con tres claves diferentes:

results.jsonjson
{ "role": "anon",          "userId": null }
{ "role": "authenticated", "userId": "b125f8cd-ddc8-4042-9d9d-2e0aa3cebe51" }
{ "role": "service_role",  "userId": null }
Una persona que llama no puede falsificar estos encabezados

La plataforma descarta authorization, apikey, x-request-id y cada encabezado x-aura-* que una persona que llama coloca en headers, cualquiera que sea su caso. Sólo los valores que él mismo verificó alcanzan su función. Otros encabezados personalizados pasan sin cambios.

No hay identificación de solicitud dentro de la función

El x-request-id de la llamada no se reenvía a su función. Para correlacionar una llamada con una línea de registro, genere su propia identificación, envíela en headers y regístrela en la función.

#
HTTP

4. Llamar a través de HTTP

Sin el SDK, envíe un objeto JSON que describa la solicitud. El campo body es lo que recibe su función.

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

Se requieren tanto apikey como Content-Type: application/json. Agregue Authorization: Bearer <user JWT> para llamar como usuario registrado. La respuesta predeterminada es un sobre; el encabezado X-Aurabase-Invoke-Mode: raw devuelve la propia respuesta de su función; consulte respuestas no JSON.

#
Resultado

5. Lee el resultado

invoke nunca lanza. Devuelve { data, error }:

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

if (error) {
  // error.status: estado HTTP del error
  // error.message: el texto que devolvió su función o la explicación de la plataforma
  return
}
// los datos son nulos cuando la función no devuelve contenido (por ejemplo, un 204)
if (data === null) return
console.log(data)

Pruebe data en lugar de error cuando necesite el valor: TypeScript entonces sabrá que no es null. Para manejar las fallas con precisión, lea errores, tiempos de espera y reintentos.

Última actualización · 12 oct 2026