Module :
azure.functions
Module Overview
Annotation based Azure Functions extension implementation for Ballerina.
- For information on the operations, which you can perform with this module, see Objects.
- For more information on the deployment, see the Azure Functions Deployment Guide.
- For examples on the usage of the operations, see the Azure Functions Deployment Example.
Azure Setup
- An Azure "Function App" needs to be created in a given resource group with the following requirements
- Runtime stack - "Java 8"
- Hosting operating system - "Windows" (default; Linux is not supported in Azure for custom handlers at the moment)
Supported Annotations:
@azure.functions:Function
Custom 'host.json'
A custom host.json file for the functions deployment can be optionally provided by placing a 'host.json' file in the current working directory where the Ballerina build is done. The required host.json properties are provided/overridden by the values derived from the source code by the compiler extension.
Usage Sample:
import ballerina/system;
import ballerinax/azure.functions as af;
// HTTP request/response with no authentication
@af:Function
public function hello(@af:HTTPTrigger { authLevel: "anonymous" } string payload)
returns @af:HTTPOutput string|error {
return "Hello, " + payload + "!";
}
// HTTP request to add data to a queue
@af:Function
public function fromHttpToQueue(af:Context ctx,
@af:HTTPTrigger {} af:HTTPRequest req,
@af:QueueOutput { queueName: "queue1" } af:StringOutputBinding msg)
returns @af:HTTPOutput af:HTTPBinding {
msg.value = req.body;
return { statusCode: 200, payload: "Request: " + req.toString() };
}
// A message put to a queue is copied to another queue
@af:Function
public function fromQueueToQueue(af:Context ctx,
@af:QueueTrigger { queueName: "queue2" } string inMsg,
@af:QueueOutput { queueName: "queue3" } af:StringOutputBinding outMsg) {
ctx.log("In Message: " + inMsg);
ctx.log("Metadata: " + ctx.metadata.toString());
outMsg.value = inMsg;
}
// A blob added to a container is copied to a queue
@af:Function
public function fromBlobToQueue(af:Context ctx,
@af:BlobTrigger { path: "bpath1/{name}" } byte[] blobIn,
@af:BindingName { } string name,
@af:QueueOutput { queueName: "queue3" } af:StringOutputBinding outMsg)
returns error? {
outMsg.value = "Name: " + name + " Content: " + blobIn.toString();
}
// HTTP request to read a blob value
@af:Function
public function httpTriggerBlobInput(@af:HTTPTrigger { } af:HTTPRequest req,
@af:BlobInput { path: "bpath1/{Query.name}" } byte[]? blobIn)
returns @af:HTTPOutput string {
int length = 0;
if blobIn is byte[] {
length = blobIn.length();
}
return "Blob: " + req.query["name"].toString() + " Length: " +
length.toString() + " Content: " + blobIn.toString();
}
// HTTP request to add a new blob
@af:Function
public function httpTriggerBlobOutput(@af:HTTPTrigger { } af:HTTPRequest req,
@af:BlobOutput { path: "bpath1/{Query.name}" } af:StringOutputBinding bb)
returns @af:HTTPOutput string|error {
bb.value = req.body;
return "Blob: " + req.query["name"].toString() + " Content: " +
bb?.value.toString();
}
// Sending an SMS
@af:Function
public function sendSMS(@af:HTTPTrigger { } af:HTTPRequest req,
@af:TwilioSmsOutput { fromNumber: "+12069845840" }
af:TwilioSmsOutputBinding tb)
returns @af:HTTPOutput string {
tb.to = req.query["to"].toString();
tb.body = req.body.toString();
return "Message - to: " + tb?.to.toString() + " body: " + tb?.body.toString();
}
public type Person record {
string id;
string name;
string country;
};
// CosmosDB record trigger
@af:Function
public function cosmosDBToQueue1(@af:CosmosDBTrigger {
connectionStringSetting: "CosmosDBConnection", databaseName: "db1",
collectionName: "c1" } Person[] req,
@af:QueueOutput { queueName: "queue3" } af:StringOutputBinding outMsg) {
outMsg.value = req.toString();
}
@af:Function
public function cosmosDBToQueue2(@af:CosmosDBTrigger {
connectionStringSetting: "CosmosDBConnection", databaseName: "db1",
collectionName: "c2" } json req,
@af:QueueOutput { queueName: "queue3" } af:StringOutputBinding outMsg) {
outMsg.value = req.toString();
}
// HTTP request to read CosmosDB records
@af:Function
public function httpTriggerCosmosDBInput1(
@af:HTTPTrigger { } af:HTTPRequest httpReq,
@af:CosmosDBInput { connectionStringSetting: "CosmosDBConnection",
databaseName: "db1", collectionName: "c1",
id: "{Query.id}", partitionKey: "{Query.country}" } json dbReq)
returns @af:HTTPOutput string|error {
return dbReq.toString();
}
@af:Function
public function httpTriggerCosmosDBInput2(
@af:HTTPTrigger { } af:HTTPRequest httpReq,
@af:CosmosDBInput { connectionStringSetting: "CosmosDBConnection",
databaseName: "db1", collectionName: "c1",
id: "{Query.id}", partitionKey: "{Query.country}" } Person? dbReq)
returns @af:HTTPOutput string|error {
return dbReq.toString();
}
@af:Function
public function httpTriggerCosmosDBInput3(
@af:HTTPTrigger { route: "c1/{country}" } af:HTTPRequest httpReq,
@af:CosmosDBInput { connectionStringSetting: "CosmosDBConnection",
databaseName: "db1", collectionName: "c1",
sqlQuery: "select * from c1 where c1.country = {country}" }
Person[] dbReq)
returns @af:HTTPOutput string|error {
return dbReq.toString();
}
// HTTP request to write records to CosmosDB
@af:Function
public function httpTriggerCosmosDBOutput1(
@af:HTTPTrigger { } af:HTTPRequest httpReq, @af:HTTPOutput af:HTTPBinding hb)
returns @af:CosmosDBOutput { connectionStringSetting: "CosmosDBConnection",
databaseName: "db1", collectionName: "c1" } json {
json entry = { id: system:uuid(), name: "Saman", country: "Sri Lanka" };
hb.payload = "Adding entry: " + entry.toString();
return entry;
}
@af:Function
public function httpTriggerCosmosDBOutput2(
@af:HTTPTrigger { } af:HTTPRequest httpReq,
@af:HTTPOutput af:HTTPBinding hb)
returns @af:CosmosDBOutput {
connectionStringSetting: "CosmosDBConnection",
databaseName: "db1", collectionName: "c1" } json {
json entry = [{ id: system:uuid(), name: "John Doe A", country: "USA" },
{ id: system:uuid(), name: "John Doe B", country: "USA" }];
hb.payload = "Adding entries: " + entry.toString();
return entry;
}
@af:Function
public function httpTriggerCosmosDBOutput3(
@af:HTTPTrigger { } af:HTTPRequest httpReq)
returns @af:CosmosDBOutput {
connectionStringSetting: "CosmosDBConnection",
databaseName: "db1", collectionName: "c1" } Person[] {
Person[] persons = [];
persons.push({id: system:uuid(), name: "Jack", country: "UK"});
persons.push({id: system:uuid(), name: "Will", country: "UK"});
return persons;
}
// A timer function which is executed every 10 seconds.
@af:Function
public function queuePopulationTimer(
@af:TimerTrigger { schedule: "*/10 * * * * *" } json triggerInfo,
@af:QueueOutput { queueName: "queue4" } af:StringOutputBinding msg) {
msg.value = triggerInfo.toString();
}
The output of the Ballerina build is as follows:
$ ballerina build azure_functions_deployment.bal
Compiling source
azure_functions_deployment.bal
Generating executables
azure_functions_deployment.jar
@azure.functions:Function: hello, fromHttpToQueue, fromQueueToQueue, fromBlobToQueue, httpTriggerBlobInput, httpTriggerBlobOutput, sendSMS, cosmosDBToQueue1, cosmosDBToQueue2, httpTriggerCosmosDBInput1, httpTriggerCosmosDBInput2, httpTriggerCosmosDBInput3, httpTriggerCosmosDBOutput1, httpTriggerCosmosDBOutput2, httpTriggerCosmosDBOutput3, queuePopulationTimer
| BindingNameConfiguration |
BindingName annotation configuration. |
| BlobConfiguration |
Blob annotation configuration. |
| BytesOutputBinding |
Byte array output binding data. |
| CosmosDBInputConfiguration |
CosmosDB input annotation configuration. |
| CosmosDBOutputConfiguration |
CosmosDB output annotation configuration. |
| CosmosDBTriggerConfiguration |
CosmosDB trigger annotation configuration. |
| HTTPBinding |
HTTP binding data. |
| HTTPRequest |
HTTP request binding data. |
| HTTPTriggerConfiguration |
HTTPTrigger annotation configuration. |
| HandlerParams |
INTERNAL stucture - the request handler parameter data. |
| QueueConfiguration |
Queue annotation configuration. |
| StringOutputBinding |
String output binding data. |
| TimerTriggerConfiguration |
TimerTrigger annotation configuration. |
| TwilioSmsConfiguration |
Twilio annotation configuration. |
| TwilioSmsOutputBinding |
Twilion SMS output binding data. |
| Context |
The request context holder. |
| __register |
INTERNAL usage - registers a handler function. |
| createContext |
I
INTERNAL usage - creates function context. |
| getBallerinaValueFromInputData |
I
INTERNAL usage - Returns a converted Ballerina value from input data. |
| getBallerinaValueFromInputDataDoubleEscape |
I
INTERNAL usage - Returns the converted Ballerina value from input data - double escape. |
| getBinaryFromHTTPReq |
I
INTERNAL usage - Returns the binary payload from the HTTP request. |
| getBodyFromHTTPInputData |
INTERNAL usage - Returns the HTTP body value from input data. |
| getBytesFromInputData |
I
INTERNAL usage - Returns the binary value from input data. |
| getHTTPRequestFromInputData |
INTERNAL usage - Populates the HTTP request structure from an input data entry. |
| getHTTPRequestFromParams |
I
INTERNAL usage - Returns the HTTP request data. |
| getJsonFromHTTPReq |
I
INTERNAL usage - Returns the JSON payload from the HTTP request. |
| getJsonFromInputData |
I
INTERNAL usage - Returns the JSON value from input data. |
| getJsonFromInputDataDoubleEscaped |
I
INTERNAL usage - Returns the JSON value from input data - double escape. |
| getJsonFromMetadata |
I
INTERNAL usage - Returns a json value from metadata. |
| getMetadata |
I
INTERNAL usage - extracts the metadata. |
| getOptionalBallerinaValueFromInputDataDoubleEscape |
I
INTERNAL usage - Returns the optional converted Ballerina value from input data - double escape. |
| getOptionalBytesFromInputData |
I
INTERNAL usage - Returns the optional binary value from input data. |
| getOptionalStringConvertedBytesFromInputData |
I
INTERNAL usage - Returns the optional string value converted from input binary data. |
| getOptionalStringFromInputData |
I
INTERNAL usage - Returns the optional string value from input data. |
| getStringConvertedBytesFromInputData |
I
INTERNAL usage - Returns the string value converted from input binary data. |
| getStringFromHTTPReq |
I
INTERNAL usage - Returns the string payload from the HTTP request. |
| getStringFromInputData |
I
INTERNAL usage - Returns the string value from input data. |
| getStringFromMetadata |
I
INTERNAL usage - Returns a string value from metadata. |
| setBallerinaValueAsJsonReturn |
I
INTERNAL usage - Converts a Ballerina value to a JSON and set the return value. |
| setBlobOutput |
I
INTERNAL usage - Sets the Blob output. |
| setCosmosDBBallerinaValueAsJsonReturn |
I
INTERNAL usage - Converts a CosmosDS Ballerina value to a JSON and set the return value. |
| setCosmosDBJsonReturn |
I
INTERNAL usage - Sets the CosmosDS JSON return value. |
| setHTTPOutput |
I
INTERNAL usage - Sets the HTTP output. |
| setHTTPReturn |
I
INTERNAL usage - Sets the HTTP binding return value. |
| setJsonReturn |
I
INTERNAL usage - Sets the JSON return value. |
| setPureHTTPOutput |
I
INTERNAL usage - Sets the pure HTTP output. |
| setPureJsonOutput |
I
INTERNAL usage - Sets the pure JSON output. |
| setPureStringOutput |
I
INTERNAL usage - Sets the pure string output. |
| setStringOutput |
I
INTERNAL usage - Sets the string output. |
| setStringReturn |
I
INTERNAL usage - Sets the string return value. |
| setTwilioSmsOutput |
I
INTERNAL usage - Sets the Twilio output. |
| BindingName |
@azurefunctions:BindingName annotation. |
| BlobInput |
@azurefunctions:BlobInput annotation. |
| BlobOutput |
@azurefunctions:BlobOutput annotation. |
| BlobTrigger |
@azurefunctions:BlobTrigger annotation. |
| CosmosDBInput |
@azurefunctions:CosmosDBInput annotation. |
| CosmosDBOutput |
@azurefunctions:CosmosDBOutput annotation. |
| CosmosDBTrigger |
@azurefunctions:CosmosDBTrigger annotation. |
| Function |
@azurefunctions:Function annotation. |
| HTTPOutput |
@azurefunctions:HTTPOutput annotation |
| HTTPTrigger |
@azurefunctions:HTTPTrigger annotation. |
| QueueOutput |
@azurefunctions:QueueOutput annotation. |
| QueueTrigger |
@azurefunctions:QueueOutput annotation. |
| TimerTrigger |
@azurefunctions:TimerTrigger annotation. |
| TwilioSmsOutput |
@azurefunctions:TwilioSmsOutput annotation. |