Invoking Functions

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 the Fn Project CLI or the Oracle Cloud Infrastructure CLI to invoke a function, authentication is handled for you. See Using the Fn Project CLI to Invoke Functions and Using the Oracle Cloud Infrastructure CLI to Invoke Functions.

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:

Using the Oracle Cloud Infrastructure CLI raw-request command. See Sending a Signed Request to a Function's Invoke Endpoint (using the Oracle Cloud Infrastructure CLI raw-request command).
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).

Using the Fn Project CLI to Invoke Functions

To invoke a function deployed to OCI Functions using the Fn Project CLI:

Log in to your development environment as a functions developer.
In a terminal window, enter:
```
fn invoke <app-name> <function-name>
```
where:
- <app-name> is the name of the application containing the function you want to invoke
- <function-name> is the name of the function you want to invoke
For example:
```
fn invoke helloworld-app helloworld-func
```
Output:
```
Hello World !
```
Tip

If you want to pass arguments and values to a function, prefix the fn invoke command with echo -n '<argument>=<value>' |

If the function is expecting the argument and value as JSON, use a valid JSON format. For example:
```
echo -n '{"name":"John"}' | fn invoke helloworld-app helloworld-func
```
Output:
```
Hello John !
```

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:
```
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:
- ```
oci fn function invoke --function-id ocid1.fnfunc.oc1.phx.aaaa____uxoa --file "-" --body ""
```
  Output:
```
Hello World !
```
- ```
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.

For information about using the API and signing requests, see REST API documentation and Security Credentials. For information about SDKs, see SDKs and the CLI.

Use the InvokeFunction API operation to invoke functions.

Obtaining a Function's Invoke Endpoint

When invoking a function using the Oracle Cloud Infrastructure CLI raw-request command, you have to specify the function's invoke endpoint.

To obtain a function's invoke endpoint:

Log in to your development environment as a functions developer.
In a terminal window, enter:
```
fn inspect function <app-name> <function-name>
```
where:
- <app-name> is the name of the application containing the function for which you want to obtain the invoke endpoint
- <function-name> is the name of the function for which you want to obtain the invoke endpoint
For example:
```
fn inspect function helloworld-app helloworld-func
```
Output:
```
{
   "annotations": {
		"fnproject.io/fn/invokeEndpoint": "https://fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke",

...
}
```
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.
Obtain the function's invoke endpoint (see Obtaining a Function's Invoke Endpoint).

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:

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:

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:

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