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.
- 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 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 a 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:QueueOutput {queueName: "people"} string { return person.name + " is " + person.age.toString() + " years old."; } }
Execute the bal build
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
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 andc1
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 onUpdated(DBEntry[] entries) returns @af:QueueOutput {queueName: "people"} string { string name = entries[0].name; log:printInfo(entries.toJsonString()); return "Hello, " + name; } }
Execute the bal build
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.
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.