Documentación de Oracle Cloud Infrastructure

Llamadas a funciones

Descubra las diferentes formas de llamar a funciones desplegadas en OCI Functions.

Puede llamar a una función desplegada en OCI Functions de distintas formas:

  • Con la CLI de Fn Project
  • Con la CLI de Oracle Cloud Infrastructure
  • Con los SDK de Oracle Cloud Infrastructure
  • Mediante la creación de una solicitud HTTP firmada al punto final de llamada de la función Cada función tiene un punto final de llamada.

Cada una de las opciones anteriores llama a la función mediante solicitudes a la API. Cualquier solicitud a la API se debe autenticar incluyendo una firma y el OCID del compartimento al que pertenece la función en la cabecera de la solicitud. Dicha solicitud se denomina solicitud "firmada". La firma incluye las credenciales de Oracle Cloud Infrastructure con formato cifrado.

Si utiliza la CLI de Fn Project o la CLI de Oracle Cloud Infrastructure para llamar a una función, se gestionará la autenticación. Consulte Uso de la CLI de Fn Project para llamar a funciones y Uso de la CLI de Oracle Cloud Infrastructure para llamar a funciones.

Si utiliza un SDK de Oracle Cloud Infrastructure para llamar a una función, puede utilizar el SDK para gestionar la autenticación. Consulte Uso de SDK para llamar a funciones.

Si crea una solicitud HTTP firmada para el punto final de llamada de una función, tendrá que gestionar la autenticación mediante la inclusión de una firma y el OCID del compartimento al que pertenece la función en la cabecera de la solicitud. Puede hacerlo de distintas formas:

Tenga en cuenta que la forma de llamar a una función y el tipo de llamada que especifique determinan la cantidad máxima de tiempo que puede ejecutar la función y otros comportamientos de ejecución.

Consejo

Si no puede completar correctamente uno de los pasos de este tema, revise las soluciones para problemas comunes (consulte Solución de problemas de OCI Functions).

Tipos de Llamada Síncrona y Desasociada

Al llamar a una función, puede especificar un tipo para la llamada a la función. El tipo de llamada de función determina la responsabilidad del manejo de resultados, cuando se devuelve el control al emisor de la llamada y el código de estado HTTP que se devuelve, de la siguiente manera:

  • Sincronización: si especifica la sincronización como tipo de llamada de función (valor por defecto), OCI Functions ejecuta la solicitud de forma síncrona. Cuando se completa correctamente, OCI Functions emite un código de estado HTTP 200 y devuelve el resultado al emisor de la llamada, junto con el control.
  • Desasociado: si especifica Desasociado como tipo de llamada de función, OCI Functions ejecuta la solicitud de forma asíncrona. Tan pronto como comienza el procesamiento, OCI Functions emite un código de estado HTTP 202 y devuelve el control al emisor de la llamada. La función en sí es responsable del manejo de los resultados.

La especificación de Sync como tipo de llamada de función también se conoce como llamada a la función en modo de sincronización o como llamada síncrona. La especificación de Desasociado como tipo de llamada de función también se conoce como llamada a la función en modo Desasociado o como llamada desasociada.

La llamada desasociada puede ser mejor que la llamada síncrona para las funciones que tardan mucho tiempo en ejecutarse, ya que la llamada desasociada soporta un timeout de ejecución más largo y también soporta opciones de configuración adicionales para destinos de entrega posteriores a la ejecución (consulte Invocación de Funciones en Modo Desasociado). Las ventajas de la llamada desasociada suelen ser muy útiles para las funciones que programa para que se ejecuten en un programa recurrente. Por lo tanto, las funciones que programa siempre se invocan con Desasociado como tipo de llamada (consulte Funciones de programación).

Para especificar el tipo de llamada a la función:

  • Al llamar a una función mediante el comando fn function invoke de la CLI de OCI, utilice el parámetro --fn-invoke-type. Por ejemplo:
    oci fn function invoke --function-id ocid1.fnfunc.oc1.phx.aaaa____uxoa --file "-" --body "" --fn-invoke-type "detached"
  • Al llamar a una función desde otra función mediante una de las FDK, especifique el tipo de llamada en la llamada de función. Por ejemplo, utilizando Python FDK:
    resp = client.invoke_function(function_id=function_ocid, invoke_function_body=function_body, fn_invoke_type='detached')
  • Al llamar a una función mediante el comando raw-request de la CLI de OCI, incluya "fn-invoke-type" en el parámetro --request- headers. Por ejemplo:
    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 Función, Timeout de Llamada a Función y Timeout de Ejecución de Función

El timeout de función se puede definir con mayor precisión como:

  • Timeout de Llamada de Función, que hace referencia al tiempo que un cliente que llama a una función esperará una respuesta de la función antes de darse por vencido.
  • Timeout de ejecución de función, que hace referencia al tiempo que OCI Functions permitirá que se ejecute una función antes de terminar la ejecución.

Al llamar a una función con Sync como tipo de llamada, el timeout de llamada a la función y el timeout de ejecución de la función son efectivamente los mismos. Sin embargo, al llamar a una función con Desasociado como tipo de llamada, el parámetro Timeout de Llamada Desasociado (detachedModeTimeoutInSeconds) controla el timeout de ejecución de la función y es independiente del timeout de llamada a la función.

La forma de llamar a una función y el tipo de llamada que especifique determinan la cantidad máxima de tiempo durante la que se puede ejecutar la función, de la siguiente manera:

  • Si llama a una función mediante la CLI de Fn Project (con la sincronización como tipo de llamada), se aplica el parámetro Timeout de llamada síncrona (timeoutInSeconds) que especifique en la definición de función (el valor por defecto es 30 segundos). Consulte Changing Default Memory and Timeout Settings.
  • Si llama a una función mediante la CLI de Oracle Cloud Infrastructure (con Sync como tipo de llamada), se aplica el valor del parámetro global --read-timeout de la CLI de OCI (el valor por defecto es 60 segundos). Consulte oci fn function invoke.
  • Si llama a una función mediante los SDK de Oracle Cloud Infrastructure (con Sync como tipo de llamada), se aplica el timeout de lectura especificado para el cliente. Por ejemplo, consulte la documentación del SDK de Java y el SDK de Python.
  • Si llama a una función mediante el SDK de PL/SQL, se aplica el valor UTL_HTTP.set_transfer_timeout (el valor por defecto es 60 segundos).
  • Si llama a una función desde la API de REST DBMS_CLOUD mediante DBMS_CLOUD.SEND_REQUEST, se aplica el valor de UTL_HTTP.set_transfer_timeout (el valor por defecto es 60 segundos).

  • Si llama a una función con Desasociado como tipo de llamada, se aplica el parámetro Timeout de llamada desasociado (detachedModeTimeoutInSeconds) que especifique en la definición de función (entre 5 segundos y 3600 segundos o 1 hora). Si llama a una función con Desasociado como tipo de llamada y el parámetro Timeout de Llamada Desasociado (detachedModeTimeoutInSeconds) no está definido, se aplica el valor del parámetro Timeout de Llamada Síncrona (timeoutInSeconds). Consulte Invocación de funciones en modo desasociado.

Uso de la CLI de Fn Project para llamar a funciones

Para llamar a una función desplegada en OCI Functions mediante la CLI de Fn Project:

  1. Conéctese al entorno de desarrollo como desarrollador de funciones.

  2. En una ventana de terminal, introduzca:

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

    donde:

    • <app-name> es el nombre de la aplicación que contiene la función a la que desea llamar.
    • <function-name> es el nombre de la función a la que desea llamar.

    Por ejemplo:

    fn invoke helloworld-app helloworld-func

    Salida:

    Hello World !
    Consejo

    Si desea transferir argumentos y valores a una función, agregue al comando fn invoke el prefijo echo -n '<argument>=<value>' |.

    Si la función espera el argumento y el valor como JSON, utilice un formato JSON válido. Por ejemplo:

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

    Salida:

    Hello John !

Uso de la CLI de Oracle Cloud Infrastructure para llamar a funciones

Si ha instalado la CLI de Oracle Cloud Infrastructure, puede utilizarla para enviar solicitudes de API para llamar a funciones. Entre otras cosas, la CLI de Oracle Cloud Infrastructure facilita la autenticación de Oracle Cloud Infrastructure. Para obtener información sobre el uso de la CLI de Oracle Cloud Infrastructure, consulte Interfaz de línea de comandos (CLI).

En estas instrucciones se supone lo siguiente:

  • Ya ha instalado y configurado la CLI de Oracle Cloud Infrastructure.
  • Desea llamar a una función como desarrollador de funciones configurado para su entorno de desarrollo.

Para invocar una función con la CLI de Oracle Cloud Infrastructure:

  1. Conéctese al entorno de desarrollo como desarrollador de funciones.

  2. En una ventana de terminal, introduzca:

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

    donde:

    • <function-ocid> es el OCID de la función a la que desea llamar. Para averiguar el OCID de una función, utilice el comando fn inspect para ver el valor de la propiedad id de la función (consulte Lista de funciones).
    • <output-filepath> es la ruta y el nombre de un archivo en el que escribir la respuesta. Para escribir la respuesta en stdout, especifique --file "-"
    • <request-parameters> hace referencia a argumentos y valores opcionales para transferirlos a la función. Si la función espera argumentos y valores como JSON, utilice un formato JSON válido. Por ejemplo, --body '{"name":"John"}'. Tenga en cuenta que debe incluir --body "" en la solicitud, incluso si no hay ningún parámetro de solicitud que transferir.

    Por ejemplo:

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

      Salida:

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

      Salida:

      Hello John !

Uso de SDK para llamar a funciones

Si está escribiendo un programa para llamar a una función en un lenguaje para el que existe un SDK de Oracle Cloud Infrastructure, recomendamos utilizar ese SDK para enviar solicitudes de API para llamar a la función. Entre otras cosas, el SDK facilitará la autenticación de Oracle Cloud Infrastructure.

Tenga en cuenta que al utilizar un SDK para llamar a una función, no especifica el punto final de llamada completo que especifique al utilizar el comando raw-request de la CLI de Oracle Cloud Infrastructure (consulte Obtención del punto final de llamada de una función). En su lugar, solo especifique la primera parte del punto final de llamada de la función. Por ejemplo, al utilizar un SDK, no especifique el punto final de llamada de la función como https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke. En su lugar, especifique el punto final de llamada de la función como https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com.

Para obtener más información sobre el uso de la API y la firma de solicitudes, consulte la documentación de la API de REST y Credenciales de seguridad. Para obtener información sobre los SDK, consulte Los SDK y la CLI.

Utilice la operación API de InvokeFunction para llamar a funciones.

Obtención del punto final de llamada de una función

Al llamar a una función mediante el comando raw-request de la CLI de Oracle Cloud Infrastructure, debe especificar el punto final de llamada de la función.

Para obtener el punto final de llamada de una función:

  1. Conéctese al entorno de desarrollo como desarrollador de funciones.

  2. En una ventana de terminal, introduzca:

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

    donde:

    • <app-name> es el nombre de la aplicación que contiene la función para la que desea obtener el punto final de llamada.
    • <function-name> es el nombre de la función para la que desea obtener el punto final de llamada.

    Por ejemplo:

    fn inspect function helloworld-app helloworld-func

    Salida:

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

...
}

    El punto final de llamada de la función es el valor de "fnproject.io/fn/invokeEndpoint". Por ejemplo, "https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke" (abreviado para mejorar la legibilidad).

Envío de una solicitud firmada al punto final de llamada de una función (mediante el comando raw-request de la CLI de Oracle Cloud Infrastructure)

Si ha instalado la CLI de Oracle Cloud Infrastructure, puede utilizarla para enviar solicitudes de API para llamar a funciones. Entre otras cosas, la CLI facilitará la autenticación de Oracle Cloud Infrastructure. Para obtener más información sobre el uso de la CLI de Oracle Cloud Infrastructure, consulte Interfaz de línea de comandos (CLI).

En estas instrucciones se supone lo siguiente:

  • Ya ha instalado y configurado la CLI de Oracle Cloud Infrastructure.
  • Desea llamar a una función como desarrollador de funciones configurado para su entorno de desarrollo.

Para llamar a una función desplegada en OCI Functions enviando una solicitud firmada al punto final de llamada de la función con el comando raw-request de la CLI de Oracle Cloud Infrastructure:

  1. Conéctese al entorno de desarrollo como desarrollador de funciones.

  2. Obtenga el punto final de llamada de la función (consulte Obtención del punto final de llamada de una función).

    Por ejemplo, "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 mejorar la legibilidad).

  3. Utilice el comando raw-request de la CLI de Oracle Cloud Infrastructure para llamar a la función enviando una solicitud POST firmada al punto final de llamada de la función mediante la introducción de lo siguiente:

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

    donde:

    • <invoke-endpoint> es el punto final que ha obtenido en el paso anterior.
    • <request-parameters> hace referencia a argumentos y valores opcionales para transferirlos a la función. Si la función espera argumentos y valores como JSON, utilice un formato JSON válido. Tenga en cuenta que debe incluir --request-body "" en la solicitud, aunque no haya ningún parámetro de solicitud que transferir.

    Por ejemplo:

    • 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 ""

      Salida:

      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"}'

      Salida:

      Hello John !
  4. Si se ha proporcionado una frase de contraseña para cifrar la clave de firma de API, introduzca la frase de contraseña cuando se le solicite.

Llamada a Funciones en Modo Desasociado

Llame a una función con Desasociado como tipo de llamada cuando:

  • Desea llamar a una función que tarda mucho tiempo en ejecutarse.
  • Desea que la función se ejecute de forma asíncrona, de modo que el control se devuelva al emisor de llamada inmediatamente después de que se llame a la función sin esperar los resultados de la llamada.
  • Desea especificar destinos a los que enviar los resultados de llamadas correctas y fallidas.

La llamada desasociada permite que las cargas de trabajo de larga ejecución (como grandes tareas de ETL, trabajos de IA/ML e integraciones) terminen sin estar restringidas por el timeout de llamada síncrona.

Especificación de Timeout y Destinos para Llamadas Desasociadas de una Función

Al crear o actualizar una función, puede definir opcionalmente:

  • El parámetro Timeout de Llamada Desasociado (detachedModeTimeoutInSeconds) para especificar el timeout de ejecución de la función para llamadas desasociadas
  • Success destination y Failure destination (successDestination y failureDestination respectivamente) para especificar destinos a los que enviar los resultados de las llamadas desasociadas. Tenga en cuenta que los destinos de éxito y fallo solo se aplican a las llamadas desasociadas. Si especifica un destino de éxito y/o fallo, OCI Functions ofrece:
    • Un registro de llamada al destino correcto cuando una llamada desasociada se realiza correctamente.
    • Un registro de llamada al destino de fallo cuando falla una llamada desasociada.

    Los destinos soportados para los resultados de las llamadas desasociadas son el servicio Notifications, el servicio Queue y el servicio Streaming. Tenga en cuenta que para escribir en el servicio de destino, OCI Functions necesita permisos de política de IAM (consulte Creación de políticas de IAM para destinos de fallo y éxito de llamadas desasociadas).

Puede utilizar la consola, la CLI de OCI y la API para especificar el timeout y los destinos de las llamadas desasociadas.

Por ejemplo, puede introducir el siguiente comando de la CLI de OCI para crear una función que, cuando se llama con un tipo de llamada Desasociado, se ejecuta durante un máximo de 1800 segundos antes del timeout y para la que los resultados de las llamadas correctas y fallidas se envían a los destinos especificados en success-dest.json y 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

donde:

  • success-dest.json contiene la siguiente cadena JSON:
    {"kind": "STREAM", "streamId": "ocid1.stream.oc1...."}
  • failure-dest.json contiene la siguiente cadena JSON:
    {"kind": "QUEUE", "queueId": "ocid1.queue.oc1....", "channelId": "failure1234"}

Consulte SuccessDestinationDetails y FailureDestinationDetails en la documentación de la API para ver los atributos que se deben especificar para diferentes servicios de destino.

Creación de políticas de IAM para destinos de fallo y éxito de llamadas desasociadas

OCI Functions necesita permisos de IAM para escribir los resultados de las llamadas desasociadas en los destinos de éxito y fallo que especifique en las definiciones de funciones. El servicio Notifications, el servicio Streaming y el servicio Queue son destinos de éxito y fallo soportados. Si los permisos aún no existen, debe crear las políticas de IAM adecuadas que incluyan las sentencias de política necesarias.

Por ejemplo:

  • Para permitir que OCI Functions escriba los resultados de las llamadas desasociadas en los destinos de éxito y fallo en el servicio Notifications, incluya una sentencia de política similar a la siguiente en una política de 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 OCI Functions escriba los resultados de las llamadas desasociadas en los destinos de éxito y fallo en el servicio Queue, incluya una sentencia de política similar a la siguiente en una política de 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 OCI Functions escriba los resultados de las llamadas desasociadas en los destinos de éxito y fallo en el servicio Streaming, incluya una sentencia de política similar a la siguiente en una política de 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>'}

Llamada a Funciones en Modo Desasociado

Después de definir la propiedad Timeout de Llamada Desasociado (detachedModeTimeoutInSeconds) de una función en el timeout de ejecución de la función necesaria y, opcionalmente, proporcionar destinos de éxito y fallo para los resultados de llamada (junto con las sentencias de política adecuadas para permitir que OCI Functions acceda a esos destinos), está listo para llamar a la función y especificar Desasociado como tipo de llamada.

Por ejemplo:

  • Para llamar a una función en modo desasociado mediante la CLI de OCI fn function invoke, introduzca un comando similar al siguiente:

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

  • Para llamar a una función en modo desasociado mediante el comando raw-request de la CLI de OCI, introduzca un comando similar al siguiente:

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

Entrega de resultados de llamada desasociados

Si ha proporcionado destinos de éxito y fallo para los resultados de las llamadas desasociadas de una función (y ha creado las sentencias de política adecuadas para permitir que OCI Functions acceda a esos destinos), OCI Functions ofrece:

  • Un registro de llamada al destino correcto cuando una llamada desasociada se realiza correctamente.
  • Un registro de llamada al destino de fallo cuando falla una llamada desasociada.

Ejemplo de registro de llamada para una llamada correcta:

{
  "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"
    }
  }
}

Ejemplo de registro de llamada para llamada fallida:

{
    "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"
        }
    }
}

OCI Functions ofrece registros de llamada en el formato esperado por el destino.

Si OCI Functions no puede entregar un registro de llamada a su destino (por ejemplo, debido a que faltan permisos), puede utilizar logs y métricas para realizar un seguimiento de los fallos de entrega.

Supervisión y métricas

Para diferenciar entre los tipos de llamada de sincronización y desasociada, las métricas FunctionExecutionDuration, FunctionInvocationCount y FunctionResponseCount incluyen la dimensión InvokeType.

Para realizar un seguimiento de las entregas correctas y con fallos de los registros de llamada a los destinos, utilice la métrica FunctionDetachedDeliveries.

Para obtener más información sobre las métricas de OCI Functions, consulte Métricas de función.

Consejos para la resolución de problemas con llamadas desasociadas

Si encuentra problemas con llamadas desasociadas o si los registros de llamadas no se entregan:

  • Vuelva a comprobar que existen los permisos de IAM necesarios para otorgar acceso a OCI Functions al destino (consulte Creación de políticas de IAM para destinos de fallo y éxito de llamadas desasociadas).
  • Utilice el servicio OCI Logging para revisar los mensajes de fallo. Si OCI Functions no ha podido entregar un registro de llamada a un destino, incluye el motivo en los logs de llamada en OCI Logging. La entrada de log comienza con Invocation record delivery to failure destination failed due to - ... (consulte Almacenamiento y visualización de logs de funciones).
  • Utilice la métrica FunctionDetachedDeliveries para revisar los detalles de entrega y los errores (consulte Métricas de función). Para las entregas fallidas a destinos de destino, la dimensión responseType de la métrica contiene Error y la dimensión errorMessage contiene la causa del error.