Azure Functions

The Azure Functions extension provides the functionality to expose a Ballerina function as a serverless function in the Azure Functions platform.

Prerequisites

Install the latest Ballerina distribution.
Install the Azure CLI.
Install and configure Functions Core Tools
Login to the Azure CLI by executing the az login command.
Create an Azure Function app with the given resource group with following requirements.

Note: Make sure to remember the function application name and storage account name as they will be required in the code samples.

Runtime stack - Java 11
Hosting operating system - Windows (By default, Linux is not supported in Azure for custom handlers at the moment.)

Triggers and bindings

An Azure Function consists of a trigger and optional bindings. A trigger defines how a function is invoked. A binding is an approach in which you can declaratively connect other resources to the function. There are input and output bindings. An input binding is a source of data into the function. An output binding allows outputting data from the function to an external resource. For more information, go to Azure Functions triggers and bindings concepts.

The following Azure Functions triggers and bindings are currently supported in Ballerina:

HTTP trigger and ouput binding
Queue trigger and ouput binding
Blob trigger, input binding, and output binding
Twilio SMS output binding
CosmosDB trigger, input binding, and output binding
Timer trigger

Write the function

The following Ballerina code gives an example of using an HTTP trigger to invoke the function, and an HTTP output binding to respond to the caller with a message based on the query parameter sent from the request.

Create a Ballerina package.

$ bal new azure_functions_deployment

Replace the contents of the generated BAL file with the following content.

import ballerinax/azure_functions as af;

service / on new af:HttpListener() {
    resource function get hello(string name) returns string {
        return "Hello, " + name + "!";
    }
}

In Ballerina, triggers are represented by listeners. When the af:HttpListener gets attached to the service, it implies that the function is an HTTP Trigger. The resource method behaves exactly the same as a service written from ballerina/http. It supports http:Payload, http:Header annotations for parameters. Input binding annotations can be used to annotate parameters to make use of external services in Azure. If no annotations are specified for a parameter, it is identified as a query parameter.

Output bindings are defined in the return type definition. For services with the HttpListener attachment, HttpOutput is the default output binding. You can override the default behavior by specifying them explicitly in the return type. For example, see HTTP Trigger -> Queue Output.

In the code sample shown above, it has an empty service path and resource path named hello. The accessor is get. It expects a request with a query parameter for the field name. The required artifact generation and data binding will be handled by the ballerinax/azure_functions package automatically.

Build the function

The Azure Functions functionality is implemented as a compiler extension. Thus, artifact generation happens automatically when you build a Ballerina module. Let's see how this works by building the above code.

$ bal build --cloud="azure_functions"
Compiling source
        wso2/azure_functions_deployment:0.1.0

Generating executable
        @azure_functions:Function: get-hello

        Execute the command below to deploy the function locally.
        func start --script-root target/azure_functions --java

        Execute the command below to deploy Ballerina Azure Functions.
        func azure functionapp publish <function_app_name> --script-root target/azure_functions 

        target/bin/azure_functions_deployment.jar

Deploy the function

The created function app name should be provided to the placeholders shown in the above-generated usage instructions from the compiler.

A sample execution to deploy the functions to Azure Functions is shown below.

$ func azure functionapp publish <function_app_name> --script-root target/azure_functions 
Getting site publishing info...
Creating archive for current directory...
Uploading 28.64 MB [##############################################################################]
Upload completed successfully.
Deployment completed successfully.
Syncing triggers...
Functions in bal-learn-1:
    get-hello - [httpTrigger]
        Invoke url: https://bal-learn-1.azurewebsites.net/hello

Invoke the function

The deployed Azure Function can be tested by invoking it using an HTTP client such as cURL:

$ curl https://<function_app_name>.azurewebsites.net/hello\?name\=Jack
Hello, Jack!

More samples

This section uses different types of triggers and bindings to build Azure functions to integrate with different Azure services using concepts explained in the above sections.

HTTP Trigger -> queue output

The following Ballerina code gives an example of using an HTTP trigger to invoke the function and uses multiple output bindings to return the HTTP response and queue output binding to write an entry to a queue.

First, create a queue to hold the outputs of the function by accessing the storage account that was created alongside the function app in the prerequisites. Select Queues in the sidebar in the storage accounts. Click the Add queue button, and enter the same value as the value of the queueName property in the below QueueOutput annotation.

import ballerina/http;
import ballerinax/azure_functions as af;

public type Person record {
    string name;
    int age;
};

service / on new af:HttpListener() {
    resource function post queue(@http:Payload Person person) returns [@af:HttpOutput http:Created, @af:QueueOutput {queueName: "people"} string] {
        http:Created httpRes = {
            body: person.name + " Added to the Queue!"
        };
        return [httpRes, person.name + " is " + person.age.toString() + " years old."];
    }
}

Execute the bal build --cloud="azure_functions" command on the package directory to build the package. Then, execute the func azure functionapp publish <function_app_name> --script-root target/azure_functions command shown in the Ballerina build output to deploy it.

Now, the deployed Azure Function can be tested by invoking it using an HTTP client such as cURL.

$ curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"name":"Jack","age":21}' \
  "https://<function_app_name>.azurewebsites.net/queue"
Jack Added to the Queue!

Refresh the queue page in the portal and view the added entry.

Cosmos DB trigger -> queue output

The following Ballerina code gives an example of using a Cosmos DB trigger to invoke the function and a queue output binding to write an entry to a queue.

Before writing and deploying the code, create a Cosmos DB and a queue to make use of those services later.

You can reuse the queue you created in the above HTTP trigger -> Queue output sample.
Create an Azure Cosmos DB account and select Cosmos DB Core.
Once the database is created, go to the Data Explorer, and select Create Container.
Enter db1 as Database ID and c1 as the collection ID, and click Ok.

Note: If you want to change these values, make sure to change them in the code as well. 5. Go to the Keys tab of the Cosmos DB page.

Copy the value of the PRIMARY CONNECTION STRING.
Click the Configuration tab on the Function app page.
Select New Application Setting, and paste the data you copied above as the value. For the key, use the value of the connectionStringSetting key and save.

Example application setting is as follows.

Name - `CosmosDBConnection`
Value - `AccountEndpoint=https://db-cosmos.documents.azure.com:443/;AccountKey=12345asda;`

Now, as all the infrastructure required are up and running and configured, start building and deploying the Azure function.

import ballerina/log;
import ballerinax/azure_functions as af;

public type DBEntry record {
    string id;
    string name;
};

@af:CosmosDBTrigger {connectionStringSetting: "CosmosDBConnection", databaseName: "db1", collectionName: "c1"}
listener af:CosmosDBListener cosmosEp = new ();

service "cosmos" on cosmosEp {
    remote function onUpdate(DBEntry[] entries) returns @af:QueueOutput {queueName: "people"} string {
        string name = entries[0].name;
        log:printInfo(entries.toJsonString());
        return "Hello, " + name;
    }
}

Once the function is deployed, add an item to the collection.

Navigate to the collection created in the Data Explorer.
Click New Item to add a new item to the collection.
Go to the queue page and observe the added new entry.

Info: Additionally, for debugging purposes, view the logs under the Logs stream in the function app.

Note: For a full sample with all the supported Azure Functions triggers and bindings in Ballerina, see the Azure Functions deployment example.

Azure Functions Native (Experimental)

Prerequisites

Install the latest Ballerina distribution.
Install the Azure CLI.
Install and configure the Functions Core Tools
Log in to the Azure CLI by executing the az login command.
Install and configure Docker in your machine.
Install and configure GraalVM in your machine.
Create an Azure Function app with the given resource group with the following requirements.

Note: Make sure to remember the function application name and storage account name as they will be required in the code samples.

Runtime stack - Java 11
Hosting operating system - Linux (As of now, Ballerina Azure functions native support is only available for Linux.)

Write the function

You can use any Azure Functions code in the native approach. This sample uses the same code as in the generic Azure Functions sample section for simplicity.

Create a Ballerina package.

$ bal new azure_functions_native

Replace the contents of the generated BAL file with the following content.

import ballerinax/azure_functions as af;

service / on new af:HttpListener() {
    resource function get hello(string name) returns string {
        return "Hello, " + name + "!";
    }
}

Build and test the function

An Azure Functions package supports two build options. You can find the description of each build option below.

cloud="azure_functions" - Builds the native executable to be compatible with the Azure Functions cloud.
cloud="azure_functions_local" - Builds the native executable to be compatible with your own machine for development purposes.

Note: Both build options for the non-native JVM-based approach will behave the same since the JVM is platform-independent.

This sample uses these build options along with the native build option while building the package. First, let's build the package and run it locally. This will use the GraalVM you installed on your machine to build the native image and make the generated executable compatible with your machine.

$ bal build --cloud="azure_functions_local" --native
WARNING: GraalVM Native Image generation in Ballerina is an experimental feature
Compiling source
        anjana/azure_functions_native:0.1.0

Generating executable with Native image

        @azure_functions: Building native executable compatible for the local operating system.This may take a while.

WARNING: Unknown module: org.graalvm.nativeimage.llvm specified to --add-exports
WARNING: Unknown module: org.graalvm.nativeimage.llvm specified to --add-exports
WARNING: Unknown module: org.graalvm.nativeimage.llvm specified to --add-exports
========================================================================================================================
GraalVM Native Image: Generating 'azure_functions_native' (executable)...
========================================================================================================================
[1/7] Initializing...                                                                                   (13.2s @ 0.19GB)
 Version info: 'GraalVM 22.2.0 Java 11 CE'
 Java version info: '11.0.16+8-jvmci-22.2-b06'
 C compiler: gcc (linux, x86_64, 9.4.0)
 Garbage collector: Serial GC
 2 user-specific feature(s)
 - com.oracle.svm.thirdparty.gson.GsonFeature
 - io.ballerina.stdlib.crypto.svm.BouncyCastleFeature
[2/7] Performing analysis...  [************]                                                           (140.5s @ 3.27GB)
  25,267 (94.01%) of 26,877 classes reachable
  83,145 (81.26%) of 102,324 fields reachable
 144,918 (76.01%) of 190,650 methods reachable
   1,480 classes,   671 fields, and 2,926 methods registered for reflection
      91 classes,    93 fields, and    69 methods registered for JNI access
       7 native libraries: dl, m, pthread, rt, stdc++, z
[3/7] Building universe...                                                                              (21.8s @ 2.80GB)
[4/7] Parsing methods...      [****]                                                                    (16.1s @ 3.38GB)
[5/7] Inlining methods...     [***]                                                                      (8.6s @ 2.79GB)
[6/7] Compiling methods...    [***********]                                                            (121.9s @ 4.28GB)
[7/7] Creating image...                                                                                  (9.8s @ 5.20GB)
  93.98MB (58.05%) for code area:   103,653 compilation units
  61.59MB (38.04%) for image heap:  479,895 objects and 93 resources
   6.32MB ( 3.90%) for other data
 161.89MB in total
------------------------------------------------------------------------------------------------------------------------
Top 10 packages in code area:                               Top 10 object types in image heap:
  17.97MB ballerina.http/2                                    15.66MB byte[] for code metadata
   4.30MB ballerina.http/2.types                              13.12MB byte[] for embedded resources
   3.02MB ballerina.io/1                                       6.70MB java.lang.Class
   1.88MB ballerina.file/1                                     5.11MB byte[] for java.lang.String
   1.75MB ballerina.jwt/2                                      4.64MB java.lang.String
   1.60MB sun.security.ssl                                     3.63MB byte[] for general heap data
   1.33MB ballerina.oauth2/2                                   2.31MB com.oracle.svm.core.hub.DynamicHubCompanion
   1.25MB java.lang.invoke                                     1.29MB byte[] for reflection metadata
   1.22MB com.sun.media.sound                                983.89KB java.lang.String[]
   1.06MB ballerina.lang$0046query/0                         934.65KB c.o.svm.core.hub.DynamicHub$ReflectionMetadata
  57.84MB for 914 more packages                                6.28MB for 3340 more object types
------------------------------------------------------------------------------------------------------------------------
                        26.1s (7.6% of total time) in 71 GCs | Peak RSS: 7.77GB | CPU load: 6.64
------------------------------------------------------------------------------------------------------------------------
Produced artifacts:
 <package_dir>/azure_functions_native/target/azure_functions/azure_functions_native (executable)
 <package_dir>/azure_functions_native/target/azure_functions/azure_functions_native.build_artifacts.txt (txt)
========================================================================================================================
Finished generating 'azure_functions_native' in 5m 44s.

        @azure_functions:Function: get-hello

        Execute the command below to deploy the function locally:
        $ bal build --native --cloud="azure_functions_local"
        $ func start --script-root target/azure_functions

        Execute the command below to deploy Ballerina Azure Functions:
        $ bal build --native --cloud="azure_functions"
        $ func azure functionapp publish <function_app_name> --script-root target/azure_functions

Execute the following command to run the Azure Function locally.

$ func start --script-root target/azure_functions

Azure Functions Core Tools
Core Tools Version:       4.0.4895 Commit hash: N/A  (64-bit)
Function Runtime Version: 4.13.0.19486

[2023-02-14T11:14:19.058Z] Worker process started and initialized.

Functions:

        get-hello: [GET] http://localhost:7071/hello

Execute the following command to test the function locally.

$ curl "http://localhost:7071/hello?name=Jack"
Hello, Jack!

Deploy the function

Now, you can build the package for the Azure Functions cloud. This will perform the compilation inside the Docker image to make it compatible with the Azure Functions cloud environment.

$ bal build --cloud="azure_functions" --native

You can execute the following command to deploy the Azure Function to the Azure Functions cloud.

$ func azure functionapp publish <function_app_name> --script-root target/azure_functions
Getting site publishing info...
Uploading package...
Uploading 43.23 MB [##############################################################################]
Upload completed successfully.
Deployment completed successfully.
Syncing triggers...
Functions in bal-learn-native:
    get-hello - [httpTrigger]
        Invoke url: https://bal-learn-native.azurewebsites.net/hello

Now, the deployed Azure Function can be tested by invoking it using an HTTP client such as cURL.

$ curl "https://<function_app_name>.azurewebsites.net/hello?name=Jack"
Hello, Jack!

Subscribe to our newsletter

Subscribe via RSS

In the creation of Ballerina, we were inspired by many technologies. Thank you to all that have come before us (and forgive us if we missed one): Java, Go, C, C++, D, Rust, Haskell, Kotlin, Dart, TypeScript, JavaScript, Python, Perl, Flow, Swift, Elm, RelaxNG, NPM, Crates, Maven, Gradle, Kubernetes, Docker, Envoy, Markdown, GitHub, and WSO2.

Why Ballerina

Get started

Learn the language

Distinctive language features

Featured scenarios

Learn the platform

Source code & dependencies

Style guide

Test, debug & document the code

Test Ballerina code

Run in the cloud

Code to Cloud

Function as a service

Configure & observe

Configure Ballerina programs

Java interoperability

Java interoperability guide

Ballerina tooling

CLI documentation

Ballerina persist

Azure Functions

Prerequisites

Triggers and bindings

Write the function

Build the function

Deploy the function

Invoke the function

More samples

HTTP Trigger -> queue output

Cosmos DB trigger -> queue output

Azure Functions Native (Experimental)

Prerequisites

Write the function

Build and test the function

Deploy the function