Documentação do Oracle Cloud Infrastructure

Chamando Funções

Descubra as diferentes maneiras de chamar funções implantadas no OCI Functions.

Você pode chamar uma função que implantou no OCI Functions de diversas maneiras:

  • Usando a CLI do Fn Project.
  • Usando a CLI do Oracle Cloud Infrastructure.
  • Usando os SDKs do Oracle Cloud Infrastructure.
  • Fazendo uma solicitação HTTP assinada para o ponto final de chamada da função. Cada função tem um ponto final de chamada.

Cada uma das chamadas acima chama a função por meio de solicitações à API. Qualquer solicitação à API deve ser autenticada incluindo uma assinatura e o OCID do compartimento ao qual a função pertence no cabeçalho da solicitação. Tal solicitação é referenciada como uma solicitação 'assinada'. A assinatura inclui credenciais do Oracle Cloud Infrastructure em um formato criptografado.

Se você usar a CLI do Fn Project ou a CLI do Oracle Cloud Infrastructure para chamar uma função, a autenticação será tratada para você. Consulte Usando a CLI do Fn Project para Chamar Funções e Usando a CLI do Oracle Cloud Infrastructure para Chamar Funções.

Se você usar um SDK do Oracle Cloud Infrastructure para chamar uma função, poderá usar o SDK para tratar a autenticação. Consulte Usando SDKs para Chamar Funções.

Se você fizer uma solicitação HTTP assinada para um ponto final de chamada da função, você terá de tratar a autenticação incluindo uma assinatura e o OCID do compartimento ao qual a função pertence no cabeçalho da solicitação. Você pode fazer isso de diversas maneiras:

Observe que a forma como você chama uma função e o tipo de chamada que você especifica determina o tempo máximo que a função pode executar e outros comportamentos de execução.

Dica

Se você não puder concluir com sucesso uma das etapas deste tópico, consulte as soluções para problemas comuns (consulte Diagnóstico e Solução de Problemas do OCI Functions).

Tipos de Chamada Síncrona e Desanexada

Ao chamar uma função, você pode especificar um tipo para a chamada de função. O tipo de chamada de função determina a responsabilidade pelo tratamento de resultados, quando o controle é retornado ao chamador e o código de status HTTP retornado, da seguinte forma:

  • Sincronização: Se você especificar a Sincronização como o tipo de chamada de função (o padrão), o OCI Functions executará a solicitação de forma síncrona. Após a conclusão bem-sucedida, o OCI Functions emite um código de status HTTP 200 e retorna o resultado ao chamador, juntamente com o controle.
  • Desanexado: Se você especificar Desanexado como o tipo de chamada de função, o OCI Functions executará a solicitação de forma assíncrona. Assim que o processamento começa, o OCI Functions emite um código de status HTTP 202 e retorna o controle para o chamador. A função em si é responsável pelo tratamento de resultados.

Especificar a Sincronização como o tipo de chamada de função também é conhecido como chamar a função no modo de Sincronização ou como chamada síncrona. Especificar Desanexado como o tipo de chamada de função também é conhecido como chamar a função no modo Desanexado ou como chamada desanexada.

A chamada desanexada pode ser melhor do que a chamada síncrona para funções que levam muito tempo para serem executadas, porque a chamada desanexada suporta um timeout de execução mais longo e também suporta opções de configuração adicionais para destinos de entrega pós-execução (consulte Chamando Funções no Modo Desanexado). Os benefícios da chamada desanexada geralmente são muito úteis para funções que você programar para serem executadas em uma programação recorrente. Portanto, as funções que você programa sempre são chamadas com Desanexado como o tipo de chamada (consulte Funções de Programação).

Para especificar o tipo de chamada de função:

  • Ao chamar uma função usando o comando fn function invoke da CLI do OCI, use o parâmetro --fn-invoke-type. Por exemplo:
    oci fn function invoke --function-id ocid1.fnfunc.oc1.phx.aaaa____uxoa --file "-" --body "" --fn-invoke-type "detached"
  • Ao chamar uma função de outra função usando uma das FDKs, especifique o tipo de chamada na chamada de função. Por exemplo, usando o Python FDK:
    resp = client.invoke_function(function_id=function_ocid, invoke_function_body=function_body, fn_invoke_type='detached')
  • Ao chamar uma função usando o comando raw-request da CLI do OCI, inclua "fn-invoke-type" no parâmetro --request- headers. Por exemplo:
    oci raw-request --http-method POST --target-uri https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke --request-body ""  --request-headers '{"fn-invoke-type" : "detached"}'

Timeout de Função, Timeout de Chamada de Função e Timeout de Execução de Função

O timeout da função pode ser definido com mais precisão como:

  • Timeout de chamada de função, que se refere ao período de tempo que um cliente que chama uma função aguardará uma resposta da função antes de desistir.
  • Timeout de execução da função, que se refere ao tempo durante o qual o OCI Functions permitirá que uma função seja executada antes de encerrar a execução.

Quando você chama uma função com Sync como o tipo de chamada, o timeout de chamada da função e o timeout de execução da função são efetivamente os mesmos. No entanto, quando você chama uma função com Desanexado como tipo de chamada, o parâmetro Timeout de chamada desanexado (detachedModeTimeoutInSeconds) controla o timeout de execução da função e é separado do timeout de chamada da função.

A forma como você chama uma função e o tipo de chamada que você especifica determinam o tempo máximo pelo qual a função pode ser executada, da seguinte forma:

  • Se você chamar uma função usando a CLI do Fn Project (com a Sincronização como o tipo de chamada), o parâmetro Timeout de chamada síncrona (timeoutInSeconds) especificado na definição da função será aplicado (o padrão é 30 segundos). Consulte Alterando Definições Padrão de Memória e Timeout.
  • Se você chamar uma função usando a CLI do Oracle Cloud Infrastructure (com o Sync como o tipo de chamada), o valor do parâmetro global --read-timeout da CLI do OCI será aplicado (o padrão é 60 segundos). Consulte oci fn function call.
  • Se você chamar uma função usando os SDKs do Oracle Cloud Infrastructure (com o Sync como o tipo de chamada), o timeout de leitura especificado para o cliente será aplicado. Por exemplo, consulte a documentação Java SDK e Python SDK.
  • Se você chamar uma função usando o SDK PL/SQL, o valor de UTL_HTTP.set_transfer_timeout será aplicado (o padrão é 60 segundos).
  • Se você chamar uma função da API REST DBMS_CLOUD usando DBMS_CLOUD.SEND_REQUEST, o valor de UTL_HTTP.set_transfer_timeout será aplicado (o padrão é 60 segundos).

  • Se você chamar uma função com Desanexado como o tipo de chamada, o parâmetro Timeout de chamada desanexado (detachedModeTimeoutInSeconds) especificado na definição da função será aplicado (entre 5 segundos e 3600 segundos ou 1 hora). Se você chamar uma função Desanexada como o tipo de chamada e o parâmetro Detached invocation timeout (detachedModeTimeoutInSeconds) não for definido, o valor do parâmetro Synchronous invocation timeout (timeoutInSeconds) será aplicado. Consulte Chamando Funções no Modo Desanexado.

Usando a CLI do Fn Project para Chamar Funções

Para chamar uma função implantada no OCI Functions usando a CLI do Fn Project:

  1. Acesse o ambiente de desenvolvimento como desenvolvedor de funções.

  2. Em uma janela de terminal, digite:

    fn invoke <app-name> <function-name>

    em que:

    • <app-name> é o nome do aplicativo que contém a função que você deseja chamar
    • <function-name> é o nome da função que você deseja chamar

    Por exemplo:

    fn invoke helloworld-app helloworld-func

    Saída:

    Hello World !
    Dica

    Se quiser passar argumentos e valores para uma função, coloque no prefixo o comando fn invoke com echo -n '<argument>=<value>' |

    Se a função estiver esperando o argumento e o valor como JSON, use um formato JSON válido. Por exemplo:

    echo -n '{"name":"John"}' | fn invoke helloworld-app helloworld-func

    Saída:

    Hello John !

Usando a CLI do Oracle Cloud Infrastructure para Chamar Funções

Se você tiver instalado a CLI do Oracle Cloud Infrastructure, poderá usá-la para enviar solicitações de API para chamar funções. Entre outras coisas, a CLI do Oracle Cloud Infrastructure facilitará a autenticação do Oracle Cloud Infrastructure. Para obter informações sobre como usar a CLI do Oracle Cloud Infrastructure, consulte Interface de Linha de Comandos (CLI).

Estas instruções consideram que:

  • você já instalou e configurou a CLI do Oracle Cloud Infrastructure
  • você deseja chamar uma função como desenvolvedor de funções que está configurada para o seu ambiente de desenvolvimento

Para chamar uma função usando a CLI do Oracle Cloud Infrastructure:

  1. Acesse o ambiente de desenvolvimento como desenvolvedor de funções.

  2. Em uma janela de terminal, digite:

    oci fn function invoke --function-id <function-ocid> --file "<output-filepath>" --body "<request-parameters>"

    em que:

    • <function-ocid> é o OCID da função que você deseja chamar. Para descobrir o OCID de uma função, use o comando fn inspect para ver o valor da propriedade id da função (consulte Listando Funções).
    • <output-filepath> é o caminho e o nome de um arquivo para gravar a resposta. Para gravar a resposta em stdout, especifique --file "-"
    • <request-parameters> são argumentos e valores opcionais para passar para a função. Se a função estiver esperando argumentos e valores como JSON, use um formato JSON válido. Por exemplo, --body '{"name":"John"}'. Observe que você deve incluir --body "" na solicitação, mesmo se não houver parâmetros de solicitação a serem aprovados.

    Por exemplo:

    • oci fn function invoke --function-id ocid1.fnfunc.oc1.phx.aaaa____uxoa --file "-" --body ""

      Saída:

      Hello World !
    • oci fn function invoke --function-id ocid1.fnfunc.oc1.phx.aaaa____uxoa --file "-" --body '{"name":"John"}'

      Saída:

      Hello John !

Usando SDKs para Chamar Funções

Se você estiver gravando um programa para chamar uma função em uma linguagem para a qual existe um SDK do Oracle Cloud Infrastructure, recomendamos que você use esse SDK para enviar solicitações de API para chamar a função. Entre outras coisas, o SDK facilitará a autenticação do Oracle Cloud Infrastructure.

Observe que, ao usar um SDK para chamar uma função, você não especifica todo o ponto final de chamada especificado ao usar o comando raw-request da CLI do Oracle Cloud Infrastructure (consulte Obtendo o Ponto Final de Chamada de uma Função). Em vez disso, especifique apenas a primeira parte do ponto final de chamada da função. Por exemplo, ao usar um SDK, não especifique o ponto final de chamada da função como https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke. Em vez disso, especifique o ponto final de chamada da função como https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com.

Para obter informações sobre como usar a API e assinar solicitações, consulte a documentação da API REST e Credenciais de Segurança. Para obter informações sobre SDKs, consulte SDKs e a CLI.

Use a operação API InvokeFunction para chamar funções.

Obtendo um Ponto Final de Chamada da Função

Ao chamar uma função usando o comando raw-request da CLI do Oracle Cloud Infrastructure, você precisa especificar o ponto final de chamada da função.

Para obter o ponto final de chamada de uma função:

  1. Acesse o ambiente de desenvolvimento como desenvolvedor de funções.

  2. Em uma janela de terminal, digite:

    fn inspect function <app-name> <function-name>

    em que:

    • <app-name> é o nome do aplicativo que contém a função para a qual você deseja obter o ponto final da chamada
    • <function-name> é o nome da função para a qual você deseja obter o ponto final de chamada

    Por exemplo:

    fn inspect function helloworld-app helloworld-func

    Saída:

    {
   "annotations": {
		"fnproject.io/fn/invokeEndpoint": "https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke",

...
}

    O ponto final de chamada da função é o valor de "fnproject.io/fn/invokeEndpoint". Por exemplo, "https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke" (abreviado para legibilidade).

Enviando uma Solicitação Assinada ao Ponto Final de Chamada de uma Função (usando o comando raw-request da CLI do Oracle Cloud Infrastructure)

Se você tiver instalado a CLI do Oracle Cloud Infrastructure, poderá usá-la para enviar solicitações de API para chamar funções. Entre outras coisas, a CLI facilitará a autenticação do Oracle Cloud Infrastructure. Para obter mais informações sobre como usar a CLI do Oracle Cloud Infrastructure, consulte Interface de Linha de Comandos (CLI).

Estas instruções consideram que:

  • você já instalou e configurou a CLI do Oracle Cloud Infrastructure
  • você deseja chamar uma função como desenvolvedor de funções que está configurada para o seu ambiente de desenvolvimento

Para chamar uma função implantada no OCI Functions enviando uma solicitação assinada para o ponto final de chamada da função usando o comando raw-request da CLI do Oracle Cloud Infrastructure:

  1. Acesse o ambiente de desenvolvimento como desenvolvedor de funções.

  2. Obtenha o ponto final de chamada da função (consulte Obtendo um Ponto Final de Chamada da Função).

    Por exemplo, "fnproject.io/fn/invokeEndpoint": "https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke" (abreviado para legibilidade).

  3. Use o comando raw-request da CLI do Oracle Cloud Infrastructure para chamar a função enviando uma solicitação POST assinada para o ponto final de chamada da função informando:

    oci raw-request --http-method POST --target-uri <invoke-endpoint> --request-body "<request-parameters>"

    em que:

    • <invoke-endpoint> é o ponto final que você obteve na etapa anterior.
    • <request-parameters> são argumentos e valores opcionais para passar para a função. Se a função estiver esperando argumentos e valores como JSON, use um formato JSON válido. Observe que você deve incluir --request-body "" na solicitação, mesmo se não houver parâmetros de solicitação a serem aprovados.

    Por exemplo:

    • oci raw-request --http-method POST --target-uri https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke --request-body ""

      Saída:

      Hello World !
    • oci raw-request --http-method POST --target-uri https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke --request-body '{"name":"John"}'

      Saída:

      Hello John !
  4. Se uma senha tiver sido fornecida para criptografar a chave de assinatura da API, informe a senha quando solicitado.

Chamando Funções em Modo Desanexado

Chame uma função Desanexada como o tipo de chamada quando:

  • Você deseja chamar uma função que leva muito tempo para ser executada.
  • Você deseja que a função seja executada de forma assíncrona, para que o controle seja retornado ao chamador imediatamente após a função ser chamada sem aguardar os resultados da chamada.
  • Você deseja especificar destinos para os quais enviar os resultados de chamadas bem-sucedidas e com falha.

A chamada desanexada permite que cargas de trabalho de longa execução (como tarefas de ETL grandes, jobs de IA/ML e integrações) sejam concluídas sem serem restritas pelo timeout de chamada síncrono.

Especificando o Timeout e os Destinos para Chamadas Desanexadas de uma Função

Ao criar ou atualizar uma função, você pode definir:

  • o parâmetro Timeout de chamada desanexado (detachedModeTimeoutInSeconds) para especificar o timeout de execução da função para chamadas desanexadas
  • o Destino de sucesso e o Destino de falha (successDestination e failureDestination, respectivamente), para especificar destinos para os quais enviar os resultados de chamadas desanexadas. Observe que os destinos de sucesso e falha se aplicam apenas a chamadas desanexadas. Se você especificar um destino de sucesso e/ou falha, o OCI Functions entregará:
    • Um registro de chamada para o destino de sucesso quando uma chamada desanexada é bem-sucedida.
    • Um registro de chamada para o destino de falha quando uma chamada desanexada falha.

    Os destinos suportados para os resultados de chamadas desanexadas são o serviço Notifications, o serviço Queue e o serviço Streaming. Observe que, para gravar no serviço de destino, o OCI Functions requer permissões de política do IAM (consulte Criando Políticas do IAM para Destinos de Sucesso e Falha de Chamada Desanexada).

Você pode usar a Console, a CLI do OCI e a API para especificar o timeout e os destinos para chamadas desanexadas.

Por exemplo, você pode informar o seguinte comando da CLI do OCI para criar uma função que, quando chamada com um tipo de chamada Desanexada, é executada por até 1800 segundos antes do timeout e para a qual os resultados de chamadas bem-sucedidas e com falha são enviados aos destinos especificados em success-dest.json e failure-dest.json, respectivamente: 

oci fn function create --application-id <ocid> --display-name "fn_longer_demo" --image <image> --memory-in-mbs 256 \
  --detached-mode-timeout-in-seconds 1800 \
  --success-destination file://success-dest.json \
  --failure-destination file://failure-dest.json

em que:

  • success-dest.json contém a seguinte string JSON:
    {"kind": "STREAM", "streamId": "ocid1.stream.oc1...."}
  • failure-dest.json contém a seguinte string JSON:
    {"kind": "QUEUE", "queueId": "ocid1.queue.oc1....", "channelId": "failure1234"}

Consulte SuccessDestinationDetails e FailureDestinationDetails na documentação da API para obter os atributos a serem especificados para diferentes serviços de destino.

Criando Políticas do IAM para Destinos de Sucesso e Falha de Chamada Desanexada

O OCI Functions requer permissões do IAM para gravar os resultados de chamadas desanexadas nos destinos de sucesso e falha especificados nas definições de função. O serviço Notifications, o serviço Streaming e o serviço Queue são destinos com suporte para sucesso e falha. Se as permissões ainda não existirem, você precisará criar políticas apropriadas do IAM que incluam as instruções de política necessárias.

Por exemplo:

  • Para permitir que o OCI Functions grave os resultados de chamadas desanexadas em destinos de sucesso e falha no serviço Notifications, inclua uma instrução de política semelhante à seguinte em uma política do serviço IAM:
    Allow any-user to use ons-topics in compartment <destination-topic-compartment-ocid> where all {request.principal.type= 'fnapp', request.principal.compartment.id='<compartment-ocid>'}
  • Para permitir que o OCI Functions grave os resultados de chamadas desanexadas em destinos de sucesso e falha no serviço Queue, inclua uma instrução de política semelhante à seguinte em uma política do serviço IAM:
    Allow any-user to use queues in compartment <destination-queue-compartment-ocid> where all {request.principal.type= 'fnapp', target.queue.id='<queue-ocid>', request.principal.compartment.id='<compartment-ocid>'}
  • Para permitir que o OCI Functions grave os resultados de chamadas desanexadas em destinos de sucesso e falha no serviço Streaming, inclua uma instrução de política semelhante à seguinte em uma política do serviço IAM:
    Allow any-user to use streams in compartment <destination-stream-compartment-ocid> where all {request.principal.type= 'fnapp', target.stream.id='<stream-ocid>', request.principal.compartment.id='<compartment-ocid>'}

Chamando Funções em Modo Desanexado

Depois de definir a propriedade Timeout de chamada desanexado (detachedModeTimeoutInSeconds) de uma função para o timeout de execução de função necessário e, opcionalmente, fornecer destinos de sucesso e falha para resultados de chamada (junto com instruções de política apropriadas para permitir que o OCI Functions acesse esses destinos), você estará pronto para chamar a função e especificar Desanexado como o tipo de chamada.

Por exemplo:

  • Para chamar uma função no modo desanexado usando a CLI fn function invoke do OCI, digite um comando semelhante ao seguinte:

    oci fn function invoke --function-id <function-ocid> --file "-" --body '{"name": "ABC"}' --fn-invoke-type detached

  • Para chamar uma função no modo desanexado usando o comando raw-request da CLI do OCI, digite um comando semelhante ao seguinte:

    oci raw-request --http-method POST --target-uri <invoke-endpoint> --request-body '{"name": "ABC"}' --request-headers '{"fn-invoke-type" : "detached"}'

Entrega de Resultados de Chamada Desanexada

Se você forneceu destinos de sucesso e falha para os resultados de chamadas desanexadas de uma função (e criou instruções de política apropriadas para permitir que o OCI Functions acesse esses destinos), o OCI Functions entrega:

  • Um registro de chamada para o destino de sucesso quando uma chamada desanexada é bem-sucedida.
  • Um registro de chamada para o destino de falha quando uma chamada desanexada falha.

Exemplo de registro de chamada para chamada bem-sucedida:

{
  "id": "01K1Q6K12C1BT01KRZJ000HKB9",
  "version": "1.0",
  "data": {
    "compartmentId": "ocid1.compartment.oc1..aaaaaaaa______jf4a",
    "functionId": "...",
    "applicationId": "...",
    "request": {
      "opcRequestId": "...",
      "fnCallId": "..."
    },
    "response": {
      "status": "200",
      "errorCode": null,
      "errorMessage": null,
      "timestamp": "2025-08-03T05:31:21.392988237Z"
    }
  }
}

Exemplo de registro de chamada para chamada com falha:

{
    "id": "01J6BS40ZC000000000000H7Z0",
    "version": "1.0",
    "data":
    {
        "compartmentId": "ocid1.compartment.oc1..aaaaaaaa______jf4a",
        "functionId": "...",
        "applicationId": "...",
        "request": {
            "opcRequestId": "...",
            "fnCallId": "..."
        },
        "response": {
            "status": "502",
            "errorCode": "FunctionInvokeExecutionFailed",
            "errorMessage": "function failed",
            "timestamp": "2024-08-11T21:47:41.264Z"
        }
    }
}

O OCI Functions entrega registros de chamada no formato esperado pelo destino.

Se o OCI Functions não puder entregar um registro de chamada ao seu destino (por exemplo, em decorrência de permissões ausentes), você poderá usar logs e métricas para rastrear falhas de entrega.

Monitoramento e Métricas

Para diferenciar entre os tipos de chamada Sincronizado e Desanexado, as métricas FunctionExecutionDuration, FunctionInvocationCount e FunctionResponseCount incluem a dimensão InvokeType.

Para rastrear entregas bem-sucedidas e com falha de registros de chamada para destinos, use a métrica FunctionDetachedDeliveries.

Para obter mais informações sobre métricas do OCI Functions, consulte Métricas de Funções.

Dicas para Solucionar Problemas com Chamadas Desanexadas

Se você encontrar problemas com chamadas desanexadas ou se os registros de chamada não forem fornecidos:

  • Verifique duas vezes se existem as permissões necessárias do IAM para conceder ao OCI Functions acesso ao destino de destino (consulte Criando Políticas do IAM para Destinos de Sucesso e Falha de Chamada Desanexada).
  • Usar o serviço OCI Logging para revisar mensagens de falha. Se o OCI Functions não puder entregar um registro de chamada a um destino de destino, ele incluirá o motivo nos logs de chamada no OCI Logging. A entrada de log começa em Invocation record delivery to failure destination failed due to - ... (consulte Armazenando e Exibindo Logs de Funções).
  • Use a métrica FunctionDetachedDeliveries para revisar detalhes e erros de entrega (consulte Métricas de Função). Para entregas com falha nos destinos de destino, a dimensão responseType da métrica contém Erro e a dimensão errorMessage contém a causa do erro.