Aura Logo
aurabasedocumentos
documentos›Edge Functions›Invoke a function

Invocar uma função

Como chamar uma função implantada com o JavaScript SDK ou por HTTP e como sua função sabe quem está chamando.

8 min lido·Nível intermediário·Revisado em 12 de out. de 2026
Este texto em inglês foi gerado automaticamente a partir do original em francês e ainda não foi revisado.
Esta página foi traduzida automaticamente. A versão em inglês é oficial.
#
SDK

1. Chame do SDK

invoke é a única chamada que uma chave pública pode fazer. Funciona da mesma forma em um navegador e em um 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
// Após o login, o SDK adiciona o JWT do usuário a cada chamada: sem código extra.
await aura.auth.signInWithPassword({ email, password })
const { data } = await aura.functions.invoke('whoami')
// A função vê x-aura-role: authenticated e o id do usuário.

O invoke<T> genérico digita apenas a resposta. O nome e o corpo não são verificados em tempo de compilação.

Uma chave pública só pode invocar

list, get, listJobs, enqueueJob e os outros métodos de gerenciamento precisam de uma chave service_role e pertencem ao seu servidor. Uma chave pública recebe 403. Veja quem pode chamar o que.

#
Solicitação

2. Descreva a solicitação

Sua função recebe exatamente a solicitação que você descreve, não um wrapper em torno dela.

OpçãoPadrãoO que a função vê
methodPOSTreq.method
path/new URL(req.url).pathname
headersnenhumreq.headers, exceto os cabeçalhos de plataforma listados abaixo
bodynenhumawait req.json() (ou req.text() para uma string)
timeoutpadrão do cliente (30 s)não visível: cancela sua chamada
signalnenhumnão visível: cancela sua chamada
responseType'json'não visível: como o SDK decodifica a resposta, consulte respostas não 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)          // nome do caminho: '/itens/1'
  const source = req.headers.get('x-source') // 'painel'
  const body = await req.json()         // {quantidade: 2}
  return Response.json({ method: req.method, id: url.pathname.split('/').pop(), source, body })
})

Regras que vale a pena conhecer:

  • GET e HEAD são enviados sem corpo.
  • Um corpo que não é uma string é enviado como JSON, com content-type: application/json, a menos que você defina um. Uma string body é enviada como está e também recebe content-type: application/json, então leia-a com req.text().
  • Sem body, a função recebe uma solicitação sem corpo. Um await req.json() simples é lançado, então escreva await req.json().catch(() => ({})) quando a chamada puder ser feita sem carga útil.
  • O corpo deve ser JSON: um objeto, array, string, número ou booleano. Um Blob, ArrayBuffer, array digitado, FormData, URLSearchParams ou ReadableStream é recusado com o código de erro invalid_body antes de qualquer solicitação ser enviada.
  • Os cabeçalhos de enquadramento (content-length, transfer-encoding, connection, host, …) são ignorados.
#
Identidade

3. Leia a identidade do chamador

A plataforma valida a chave e o token do usuário antes da execução da função e, em seguida, adiciona estes cabeçalhos:

CabeçalhoValor
x-aura-roleanon, authenticated ou service_role
x-aura-user-idO ID do usuário quando x-aura-role é authenticated, caso contrário ausente
x-aura-project-idO ID do projeto
authorizationO JWT do usuário, apenas para um usuário conectado
apikeyA chave usada para a chamada
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 reais desta chamada com três chaves diferentes:

results.jsonjson
{ "role": "anon",          "userId": null }
{ "role": "authenticated", "userId": "b125f8cd-ddc8-4042-9d9d-2e0aa3cebe51" }
{ "role": "service_role",  "userId": null }
Um chamador não pode falsificar esses cabeçalhos

A plataforma descarta authorization, apikey, x-request-id e todos os cabeçalhos x-aura-* que um chamador coloca em headers, seja qual for o caso. Somente os valores que ele verificou chegam à sua função. Outros cabeçalhos personalizados passam inalterados.

Nenhum ID de solicitação dentro da função

O x-request-id da chamada não é encaminhado para sua função. Para correlacionar uma chamada com uma linha de log, gere seu próprio id, envie-o em headers e registre-o na função.

#
HTTP

4. Chamada por HTTP

Sem o SDK, envie um objeto JSON que descreva a solicitação. O campo body é o que sua função recebe.

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

Ambos apikey e Content-Type: application/json são obrigatórios. Adicione Authorization: Bearer <user JWT> para chamar como usuário conectado. A resposta padrão é um envelope; o cabeçalho X-Aurabase-Invoke-Mode: raw retorna a própria resposta da sua função, consulte respostas não JSON.

#
Resultado

5. Leia o resultado

invoke nunca joga. Ele retorna { data, error }:

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

if (error) {
  // error.status: status HTTP da falha
  // error.message: o texto que sua função retornou ou a explicação da plataforma
  return
}
// os dados são nulos quando a função não retornou nenhum conteúdo (por exemplo, 204)
if (data === null) return
console.log(data)

Teste data em vez de error quando precisar do valor: TypeScript então saberá que não é null. Para lidar com falhas com precisão, leia erros, tempos limite e novas tentativas.

Última atualização · 12 de out. de 2026