Edit

Quickstart: Create your first function with Kotlin and Maven

  • Article

This article guides you through using the Maven command-line tool to build and publish a Kotlin function project to Azure Functions. When you're done, your function code runs on the Consumption Plan in Azure and can be triggered using an HTTP request.

If you don't have an Azure subscription, create an Azure free account before you begin.

Prerequisites

To develop functions using Kotlin, you must have the following installed:

Important

The JAVA_HOME environment variable must be set to the install location of the JDK to complete this quickstart.

Generate a new Azure Functions project

In an empty folder, run the following command to generate the Azure Functions project from a Maven archetype.

mvn archetype:generate \
    -DarchetypeGroupId=com.microsoft.azure \
    -DarchetypeArtifactId=azure-functions-kotlin-archetype

Note

If you're experiencing issues with running the command, take a look at what maven-archetype-plugin version is used. Because you are running the command in an empty directory with no .pom file, it might be attempting to use a plugin of the older version from ~/.m2/repository/org/apache/maven/plugins/maven-archetype-plugin if you upgraded your Maven from an older version. If so, try deleting the maven-archetype-plugin directory and re-running the command.

Maven asks you for values needed to finish generating the project. For groupId, artifactId, and version values, see the Maven naming conventions reference. The appName value must be unique across Azure, so Maven generates an app name based on the previously entered artifactId as a default. The packageName value determines the Kotlin package for the generated function code.

The com.fabrikam.functions and fabrikam-functions identifiers below are used as an example and to make later steps in this quickstart easier to read. You're encouraged to supply your own values to Maven in this step.

[INFO] Parameter: groupId, Value: com.fabrikam.function
[INFO] Parameter: artifactId, Value: fabrikam-function
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.fabrikam.function
[INFO] Parameter: packageInPathFormat, Value: com/fabrikam/function
[INFO] Parameter: appName, Value: fabrikam-function-20190524171507291
[INFO] Parameter: resourceGroup, Value: java-functions-group
[INFO] Parameter: package, Value: com.fabrikam.function
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: groupId, Value: com.fabrikam.function
[INFO] Parameter: appRegion, Value: westus
[INFO] Parameter: artifactId, Value: fabrikam-function

Maven creates the project files in a new folder with a name of artifactId, in this example fabrikam-functions. The ready to run generated code in the project is a simple HTTP triggered function that echoes the body of the request:

class Function {

    /**
     * This function listens at endpoint "/api/HttpTrigger-Java". Two ways to invoke it using "curl" command in bash:
     * 1. curl -d "HTTP Body" {your host}/api/HttpTrigger-Java&code={your function key}
     * 2. curl "{your host}/api/HttpTrigger-Java?name=HTTP%20Query&code={your function key}"
     * Function Key is not needed when running locally, it is used to invoke function deployed to Azure.
     * More details: https://aka.ms/functions_authorization_keys
     */
    @FunctionName("HttpTrigger-Java")
    fun run(
            @HttpTrigger(
                    name = "req",
                    methods = [HttpMethod.GET, HttpMethod.POST],
                    authLevel = AuthorizationLevel.FUNCTION) request: HttpRequestMessage<Optional<String>>,
            context: ExecutionContext): HttpResponseMessage {

        context.logger.info("HTTP trigger processed a ${request.httpMethod.name} request.")

        val query = request.queryParameters["name"]
        val name = request.body.orElse(query)

        name?.let {
            return request
                    .createResponseBuilder(HttpStatus.OK)
                    .body("Hello, $name!")
                    .build()
        }

        return request
                .createResponseBuilder(HttpStatus.BAD_REQUEST)
                .body("Please pass a name on the query string or in the request body")
                .build()
    }
}

Run the function locally

Change directory to the newly created project folder and build and run the function with Maven:

cd fabrikam-function
mvn clean package
mvn azure-functions:run

Note

If you're experiencing this exception: javax.xml.bind.JAXBException with Java 9, see the workaround on GitHub.

You see this output when the function is running locally on your system and ready to respond to HTTP requests:

Now listening on: http://0.0.0.0:7071
Application started. Press Ctrl+C to shut down.

Http Functions:

        HttpTrigger-Java: [GET,POST] http://localhost:7071/api/HttpTrigger-Java

Trigger the function from the command line using curl in a new terminal window:

curl -w '\n' -d LocalFunction http://localhost:7071/api/HttpTrigger-Java

Hello LocalFunction!

Use Ctrl-C in the terminal to stop the function code.

Deploy the function to Azure

The deploy process to Azure Functions uses account credentials from the Azure CLI. Sign in with the Azure CLI before continuing.

az login

Deploy your code into a new function app using the azure-functions:deploy Maven target.

Note

When you use Visual Studio Code to deploy your function app, remember to choose a non-free subscription, or you will get an error. You can watch your subscription on the left side of the IDE.

mvn azure-functions:deploy

When the deploy is complete, you see the URL you can use to access your function app:

[INFO] Successfully deployed Function App with package.
[INFO] Deleting deployment package from Azure Storage...
[INFO] Successfully deleted deployment package fabrikam-function-20170920120101928.20170920143621915.zip
[INFO] Successfully deployed Function App at https://fabrikam-function-20170920120101928.azurewebsites.net
[INFO] ------------------------------------------------------------------------

Test the function app running on Azure using cURL. You'll need to change the URL from the sample below to match the deployed URL for your own function app from the previous step.

Note

Make sure you set the Access rights to Anonymous. When you choose the default level of Function, you are required to present the function key in requests to access your function endpoint.

curl -w '\n' https://fabrikam-function-20170920120101928.azurewebsites.net/api/HttpTrigger-Java -d AzureFunctions

Hello AzureFunctions!

Make changes and redeploy

Edit the src/main.../Function.java source file in the generated project to alter the text returned by your function app. Change this line:

return request
        .createResponseBuilder(HttpStatus.OK)
        .body("Hello, $name!")
        .build()

To the following code:

return request
        .createResponseBuilder(HttpStatus.OK)
        .body("Hi, $name!")
        .build()

Save the changes and redeploy by running azure-functions:deploy from the terminal as before. The function app will be updated and this request:

curl -w '\n' -d AzureFunctionsTest https://fabrikam-functions-20170920120101928.azurewebsites.net/api/HttpTrigger-Java

You see the updated output:

Hi, AzureFunctionsTest

Reference bindings

To work with Azure Functions triggers and bindings other than HTTP trigger and Timer trigger, you need to install binding extensions. While not required by this article, you'll need to know how to do enable extensions when working with other binding types.

The easiest way to install binding extensions is to enable extension bundles. When you enable bundles, a predefined set of extension packages is automatically installed.

To enable extension bundles, open the host.json file and update its contents to match the following code:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.*, 4.0.0)"
    }
}

Next steps

You've created a Kotlin function app with a simple HTTP trigger and deployed it to Azure Functions.