I've written several posts here on the developer blog that show you how to create and invoke your serverless functions, but so far we've only covered how to manually invoke those functions or programmatically invoke them via the OCI Java SDK. Today I want to show you a much more powerful way to invoke your functions that responds automatically to certain actions in your cloud tenancy. This method involves utilizing the recently announced Cloud Events service which freely available within your cloud tenancy.
In this post, we'll look at triggering an Oracle Function when an object is uploaded to an Object Storage bucket in your tenancy. We'll use cloud events to call our function which will retrieve metadata from the image.
Before we get into this post, here's a list of my previous blog posts. If you're new to Oracle Functions, these posts will help get you started and should answer any questions you may have about creating and manually invoking your functions:
Let's start by creating a brand new serverless application that we can use for our function. In my previous posts, we created the application via the Fn CLI, so this time let's use the cloud dashboard instead. Start by selecting Developer Services -> Functions in the sidebar menu.
Next, click 'Create Application' and then populate the form on the next page. Note, your previously created VCNs are listed here and you can select the appropriate subnet instead of manually providing the OCID of the subnet via the Fn CLI:
Also note in the screenshot above that we can provide our log URL from Papertrail so we can view our log output later on.
Let's head back to our local terminal to create the application:
fn init --runtime java cloud-events-demo-fn
We'll add two dependencies to the
pom.xml file. One for the
cloudevents-api, and another for
metadata-extractor so we can extract the image metadata later on:
We'll write a test for our function next. You'll need to manually upload a sample image to your object storage bucket first. Then use the following JSON structure for your test (substituting the proper values for your test image name, tenancy name and bucket name):
Once you've uploaded your test image and modified that JSON, you'll be able to use it in your test which looks like so:
The test will obviously fail at this point, so let's implement the function so that our test passes. Since Oracle Cloud Events conform to the CNCF Cloud Events spec, we can safely type our incoming parameter as a
CloudEvent and the FDK will handle properly serializing the parameter when the function is triggered. Once we have our CloudEvent data we can construct a URL that points to our image (a public image in this case) and open that URL as a stream that can be passed to the metadata extractor.
At this point our test will pass and we can deploy the function to our application with:
fn deploy --app cloud-events-demo
We can manually invoke this by passing our event JSON string:
echo "[event JSON string]" | fn invoke cloud-events-demo cloud-events-demo-fn
Note! You can use
echo to pipe simple strings to
fn invoke, but if you would like to send the contents of a file you must use
Or, if you have a JSON file on disk that you would like to send, use:
cat file.json | fn invoke cloud-events-demo cloud-events-demo-fn
And we'll see that our function works as expected. Now let's create the cloud event rule!
To create a new cloud event rule, click on Application Integration -> Events Service in the sidebar menu:
Click on 'Create Rule' and populate the form:
Note the conditions above. I've selected 'Object Storage' as the 'Service Name' and 'Object Storage - Create Object' as the 'Event Type'. I'm also able to filter the events by attributes - in this case, I'm only interested in uploads to my specific bucket. There are a number of event types and filter possibilities that you can choose from. Refer to the service documentation for more information on the event types and filters. The rest of the form looks like this:
Here we are able to specify the action we would like taken when this cloud event is fired. In this case, we want to call our serverless function, but we could also publish to an Oracle Stream or invoke a notification. Click 'Create Rule' and the rule will be immediately available for use.
To test the rule, simply upload a file to the bucket that you have specified in your rule. One way to do that is via the OCI CLI:
oci os object put --bucket-name object-upload-demo-public --file /Users/trsharp/Pictures/test.jpg
After a few seconds you can check your papertrail logs to see the metatadata that we wrote to
System.out. Here is a formatted example from a test image that I have uploaded:
In this post we created a serverless function to extract image metadata that is automatically triggered upon an image being uploaded to a given object storage bucket. We learned that cloud event rules can be tied to various actions within our OCI tenancy such as Database and Object Storage activities and can automatically trigger serverless functions, notifications or publish items to an Oracle Stream.