Invoke Oracle Functions via REST

Green Line (Image © Ralf Mueller)

This post covers invoking a Function deployed on Oracle Functions via oci-curl, an Oracle Cloud Infrastructure (OCI) provided bash script, which enables request signing for OCI RESTful Services.

By the time of this writing, Oracle Functions is in Limited Availability and not released yet. So below UI screen shots, fn CLI commands and Functions API’s are still subject to change.

Setup

Lets start with a simple function deployed to Oracle Functions. Oracle Functions was announced at the KubeCon 2018 conference in Seattle. Below screen shot shows an Application deployed to Oracle Functions

ccs_weather_app Application in Oracle Functions console

and one function deployed for this Application

ccs_weather_gmail Function

It is an easy exercise to invoke this function via the fn Command Line as following

> cat payload.json | fn invoke ccs_weather_app ccs_weather_gmail

where the input payload for the function is given in file payload.json

REST invocation via OCI curl

Inspect Function

So now what if we want to invoke this function via its exposed REST endpoint? First we can inspect the function to get some more details

> fn inspect f ccs_weather_app ccs_weather_gmail

which might return something like (OCID’s shown below are not valid ones, so doesn’t make sense to give it a try, it won’t work)

Result of fn inspect

The important information here is the annotation fnproject.io/fn/invokeEndpoint which denotes the target URL for the REST call.

List Triggers

Every function exposes one or more triggers. At the point of this writing, HTTP triggers can be created when the function is initialized. The Trigger of a function is displayed in the Functions console as shown in the image above. It can also be retrieved from fn CLI with

fn list t ccs_weather_app ccs_weather_gmail

which in our example prints something like

NAME    ID      TYPE        SOURCE                       ENDPOINT
ccs_weather_gmail-trigger ocid1.fntrig.oc1.phx.XXXwqovtgjwgxpktsfbdq http /ccs_weather_gmail-trigger https://bo6ce5xeefq.us-phoenix-1.functions.oci.oraclecloud.com/t/ccs_weather_gmail-trigger

Both endpoints, the so called Invoke Endpoint and the Endpoint of the HTTP Trigger(s) can be used for REST invocations as demonstrated in the next chapter. Please note that in future releases of Oracle Functions, other types of triggers (apart from HTTP) will be added. It is important to understand, that only HTTP type Trigger Endpoints can be invoked via REST.

Setup oci-curl

The bash utility oci-curl can be downloaded from https://docs.cloud.oracle.com/iaas/Content/Resources/Assets/signing_sample_bash.txt

It is a bash script for Unix based systems, other scripts implemented in PowerShell, perl, Python etc. are also available from the Request Signatures documentation.

Users are supposed to source the script in the terminal where they want to use oci-curl as following

> source oci-curl

However, i consider it much simpler to add the script to the PATH and make it executable. For this to work , please add the following line as the first line of the script

#!/bin/bash

and then add the following line at the last line of the script

oci-curl $1 $2 $3 $4

The script itself must be modified and adjusted for the user tenancy. The following four variables must be set in the script according to your user and tenancy

local tenancyId="ocid1.tenancy.oc1..XX55gth7ioc2gbpbvqo5ecoa";
local authUserId="ocid1.user.oc1..XXXX53zsuna775rdcnxcaxxhsddu6ha";
local keyFingerprint="76:..:3b:10:57";
local privateKeyPath="/Users/someuser/.oci/oci_api_key.pem";

The information about tenancyId, authUserId, keyFingerprint can be retrieved from OCI Console. For more information about user credentials, fingerprints etc. you might want to check the following documentation

• Required Keys and OCIDs
• SDK and CLI Configuration File

Invocation of the Oracle Function REST endpoint

Now that the oci-curl script is adjusted to your user and tenancy, you can invoke the Oracle Function invoke endpoint via

> oci-curl XXXXXX.us-phoenix-1.functions.oci.oraclecloud.com \
           post ./payload.json \ "/invoke/ocid1.fnfunc.oc1.phx.aaaaaaaaXXXXXXXXXXXXXXn2tjmkzrvjg3ibyfbkpnhey7lq"

where payload.json contains the input to your function.

As an alternative to that, you can invoke the function by its HTTP Trigger Endpoint

> oci-curl XXXXXX.us-phoenix-1.functions.oci.oraclecloud.com \
           post ./payload.json \
           "/t/ccs_weather_gmail-trigger"

This ends the small article, thanks for reading all the way to the end. I might update this one with examples on how to call an Oracle Function from Java and Go, stay tuned.