Find out the different ways to invoke functions deployed to OCI Functions.
You can invoke a function that you've deployed to OCI Functions in different ways:
Using the Fn Project CLI.
Using the Oracle Cloud Infrastructure CLI.
Using the Oracle Cloud Infrastructure SDKs.
Making a signed HTTP request to the function's invoke endpoint. Every function has an invoke endpoint.
Each of the above invokes the function via requests to the API. Any request to the API must be authenticated by including a signature and the OCID of the compartment to which the function belongs in the request header. Such a request is referred to as a 'signed' request. The signature includes Oracle Cloud Infrastructure credentials in an encrypted form.
If you use an Oracle Cloud Infrastructure SDK to invoke a function, you can use the SDK to handle authentication. See Using SDKs to Invoke Functions.
If you make a signed HTTP request to a function's invoke endpoint, you'll have to handle authentication yourself by including a signature and the OCID of the compartment to which the function belongs in the request header. You can do this in different ways:
Writing code to programmatically sign requests. For information about the required credentials and how to sign the requests, see Request Signatures.
Note that how you invoke a function determines the maximum amount of time the function can run for, as follows:
If you invoke a function using the Fn Project CLI, the Timeout you specify in the function definition is applied (default is 30 seconds). See Changing Default Memory and Timeout Settings.
If you invoke a function using the Oracle Cloud Infrastructure CLI, the value of the OCI CLI --read-timeout global parameter is applied (default is 60 seconds). See oci fn function invoke.
If you invoke a function using the Oracle Cloud Infrastructure SDKs, the read timeout specified for the client is applied. For example, see the Java SDK and Python SDK documentation.
If you invoke a function using the PL/SQL SDK, the value of UTL_HTTP.set_transfer_timeout is applied (default is 60 seconds).
If you invoke a function from the DBMS_CLOUD REST API using DBMS_CLOUD.SEND_REQUEST, the value of UTL_HTTP.set_transfer_timeout is applied (default is 60 seconds).
Tip
If you aren't able to successfully complete one of the steps in this topic, review the solutions for common problems (see Troubleshooting OCI Functions).
Synchronous and Detached Invocation Types
When you invoke a function, you can specify a type for the function invocation. The function invocation type determines responsibility for result handling, when control is returned to the caller, and the HTTP status code that is returned, as follows:
Sync: If you specify Sync as the function invocation type (the default), OCI Functions executes the request. Then, on successful completion, OCI Functions issues an HTTP 200 status code and returns the result to the caller, along with control.
Detached: If you specify Detached as the function invocation type, OCI Functions executes the request. Then, as soon as processing begins, OCI Functions issues an HTTP 202 status code and returns control to the caller. The function itself is responsible for result handling.
To specify the function invocation type:
When invoking a function using the OCI CLI fn function invoke command, use the --fn-invoke-type parameter. For example:
When invoking a function from another function using one of the FDKs, specify the invocation type in the function call. For example, using the Python FDK:
Using the Oracle Cloud Infrastructure CLI to Invoke Functions 🔗
If you have installed the Oracle Cloud Infrastructure CLI, you can use it to send API requests to invoke functions. Among other things, the Oracle Cloud Infrastructure CLI will facilitate Oracle Cloud Infrastructure authentication. For information about using the Oracle Cloud Infrastructure CLI, see Command Line Interface (CLI).
These instructions assume:
you have already installed and configured the Oracle Cloud Infrastructure CLI
you want to invoke a function as the functions developer that's configured for your development environment
To invoke a function using the Oracle Cloud Infrastructure CLI:
Log in to your development environment as a functions developer.
In a terminal window, enter:
Command
CopyTry It
oci fn function invoke --function-id <function-ocid> --file "<output-filepath>" --body "<request-parameters>"
where:
<function-ocid> is the OCID of the function you want to invoke. To find out a function's OCID, use the fn inspect command to see the value of the function's id property (see Listing Functions).
<output-filepath> is the path and name of a file to write the response to. To write the response to stdout, specify --file "-"
<request-parameters> are optionally arguments and values to pass to the function. If the function is expecting arguments and values as JSON, use a valid JSON format. For example, --body '{"name":"John"}'. Note that you must include --body "" in the request, even if there are no request parameters to pass.
For example:
Command
CopyTry It
oci fn function invoke --function-id ocid1.fnfunc.oc1.phx.aaaa____uxoa --file "-" --body ""
Output:
Hello World !
Command
CopyTry It
oci fn function invoke --function-id ocid1.fnfunc.oc1.phx.aaaa____uxoa --file "-" --body '{"name":"John"}'
Output:
Hello John !
Using SDKs to Invoke Functions 🔗
If you're writing a program to invoke a function in a language for which an Oracle Cloud Infrastructure SDK exists, we recommend you use that SDK to send API requests to invoke the function. Among other things, the SDK will facilitate Oracle Cloud Infrastructure authentication.
Note that when using an SDK to invoke a function, you do not specify the entire invoke endpoint that you specify when using the Oracle Cloud Infrastructure CLI raw-request command (see Obtaining a Function's Invoke Endpoint). Instead, only specify the first part of the function's invoke endpoint. For example, when using an SDK, do not specify the function's invoke endpoint as https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke. Instead, specify the function's invoke endpoint as https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com.
The function's invoke endpoint is the value of "fnproject.io/fn/invokeEndpoint" . For example, "https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke" (abbreviated for readability).
Sending a Signed Request to a Function's Invoke Endpoint (using the Oracle Cloud Infrastructure CLI raw-request command) 🔗
If you have installed the Oracle Cloud Infrastructure CLI, you can use it to send API requests to invoke functions. Among other things, the CLI will facilitate Oracle Cloud Infrastructure authentication. For more information about using the Oracle Cloud Infrastructure CLI, see Command Line Interface (CLI).
These instructions assume:
you have already installed and configured the Oracle Cloud Infrastructure CLI
you want to invoke a function as the functions developer that's configured for your development environment
To invoke a function deployed to OCI Functions by sending a signed request to the function's invoke endpoint using the Oracle Cloud Infrastructure CLI raw-request command:
Log in to your development environment as a functions developer.
For example, "fnproject.io/fn/invokeEndpoint": "https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke" (abbreviated for readability).
Use the Oracle Cloud Infrastructure CLI raw-request command to invoke the function by sending a signed POST request to the function's invoke endpoint by entering:
Command
CopyTry It
oci raw-request --http-method POST --target-uri <invoke-endpoint> --request-body "<request-parameters>"
where:
<invoke-endpoint> is the endpoint you obtained in the earlier step.
<request-parameters> are optionally arguments and values to pass to the function. If the function is expecting arguments and values as JSON, use a valid JSON format. Note that you must include --request-body "" in the request, even if there are no request parameters to pass.
For example:
Command
CopyTry It
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 ""
Output:
Copy
Hello World !
Command
CopyTry It
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"}'
Output:
Hello John !
If a passphrase was provided to encrypt the API signing key, enter the passphrase when prompted.