Oracle Cloud Infrastructure Documentation

Invoking Functions

You can invoke a function that you've deployed to Oracle 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:

Tip

If you aren't able to successfully complete one of the steps in this topic, review the solutions for common problems (see Troubleshooting Oracle Functions).

Using the Fn Project CLI to Invoke Functions

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

  1. Log in to your development environment as a functions developer.

  2. 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
    
    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
    
    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:

  1. Log in to your development environment as a functions developer.

  2. In a terminal window, enter:

    $ oci fn function invoke <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 Viewing Functions and Applications).

    • <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 ""
      
      Hello World !
    • $ oci fn function invoke --function-id ocid1.fnfunc.oc1.phx.aaaa____uxoa --file "-" --body '{"name":"John"}'
      
      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, Oracle recommends you use that SDK to send API requests to invoke the function. Among other things, the SDK will facilitate Oracle Cloud Infrastructure authentication.

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the InvokeFunction API operation to invoke functions.

Obtaining a Function's Invoke Endpoint

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

To obtain a function's invoke endpoint:

  1. Log in to your development environment as a functions developer.

  2. 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
    
    {
       "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 Oracle Functions by sending a signed request to the function's invoke endpoint using the Oracle Cloud Infrastructure CLI raw-request command:

  1. Log in to your development environment as a functions developer.

  2. 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).

  3. 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 ""

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

      Hello John !
  4. Assuming a passphrase was provided to encrypt the API signing key (as recommended by Oracle), enter the passphrase when prompted.

Sending a Signed Request to a Function's Invoke Endpoint (using oci-curl)

When you followed the instructions to prepare your client environment for Oracle Functions, you installed and configured oci-curl in readiness for using it to invoke functions. Among other things, oci-curl will facilitate Oracle Cloud Infrastructure authentication.

These instructions assume:

To invoke a function deployed to Oracle Functions by sending a signed request to the function's invoke endpoint using oci-curl:

  1. Log in to your development environment as a functions developer.

  2. 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).

  3. In a terminal window, use the source command to set up the current shell environment for oci-curl by entering:

    $ source <path-to-script>/oci-curl.sh

    where <path-to-script> is the path to the location of the oci-curl.sh script (see 3. Create and Configure a Copy of oci-curl). For example:

    $ source ~/oci-curl/oci-curl.sh
  4. In the same terminal window in which you entered the source command, use oci-curl to invoke the function by sending a signed POST request to the function's invoke endpoint by entering:

    oci-curl "<invoke-endpoint-host>" post <filename> "<invoke-endpoint-path>"

    where:

    • <invoke-endpoint-host> is the first half of the endpoint you obtained in the earlier step, excluding https:// and up to (and including) .oraclecloud.com. For example, fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com
    • <filename> is the name of a file containing data to pass to the function (you must specify a file, even if it's empty) . For example, payload.json
    • <invoke-endpoint-path> is the second half of the endpoint you obtained in the earlier step, from (but not including) .oraclecloud.com onwards. For example, /20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke

    For example, combining the previous examples, you might enter:

    $ oci-curl "fht7ns4mn2q.us-phoenix-1.functions.oci.oraclecloud.com" post payload.json "/20181201/functions/ocid1.fnfunc.oc1.phx.aaaa____uxoa/actions/invoke"
  5. Assuming a passphrase was provided to encrypt the API signing key (as recommended by Oracle), enter the passphrase when prompted.