Azure Functions - Quickstart

We try to keep this page up to date, but the most up to date documentation can be found in our README

Pre-requisites

  1. Node.js 8.x or above
  2. Serverless CLI v1.9.0+. You can run npm i -g serverless if you don't already have it.
  3. An Azure account. If you don't already have one, you can sign up for a free trial that includes $200 of free credit.

Create a new Azure Function App

# Create Azure Function App from template
# Templates include: azure-nodejs, azure-python, azure-dotnet
$ sls create -t azure-nodejs -p <appName>
# Move into project directory
$ cd <appName>
# Install dependencies (including this plugin)
$ npm install

The serverless.yml file contains the configuration for your service. For more details on its configuration, see the docs.

Running Function App Locally (offline plugin)

At the root of your project directory, run:

# Builds necessary function bindings files and starts the function app
$ sls offline

The offline process will generate a directory for each of your functions, which will contain a file titled function.json. This will contain a relative reference to your handler file & exported function from that file as long as they are referenced correctly in serverless.yml.

After the necessary files are generated, it will start the function app from within the same shell. For HTTP functions, the local URLs will be displayed in the console when the function app is initialized.

To build the files without spawning the process to start the function app, run:

$ sls offline build

To simply start the function app without building the files, run:

$ sls offline start

To clean up files generated from the build, run:

$ sls offline cleanup

To pass additional arguments to the spawned func host start process, add them as the option spawnargs (shortcut a). Example:

$ sls offline -a "--cors *"

This works for sls offline or sls offline start

Dry-Run Deployment

Before you deploy your new function app, you may want to double check the resources that will be created, their generated names and other basic configuration info. You can run:

# -d is short for --dryrun
$ sls deploy --dryrun

This will print out a basic summary of what your deployed service will look like.

For a more detailed look into the generated ARM template for your resource group, add the --arm (or -a) flag:

$ sls deploy --dryrun --arm

Deploy Your Function App

Deploy your new service to Azure! The first time you do this, you will be asked to authenticate with your Azure account, so the serverless CLI can manage Functions on your behalf. Simply follow the provided instructions, and the deployment will continue as soon as the authentication process is completed.

$ sls deploy

For more advanced deployment scenarios, see our deployment docs

Get a Summary of Your Deployed Function App

To see a basic summary of your application (same format as the dry-run summary above), run:

$ sls info

To look at the ARM template for the last successful deployment, add the --arm (or -a) flag:

$ sls info --arm

You can also get information services with different stages, regions or resource groups by passing any of those flags. Example:

$ sls info --stage prod --region westus2

Test Your Function App

Invoke your HTTP functions without ever leaving the CLI using:

$ sls invoke -f <functionName>
Invoke Options
  • -f or --function - Function to Invoke
  • -d or --data - Stringified JSON data to use as either query params or request body
  • -p or --path - Path to JSON file to use as either query params or request body
  • -m or --method - HTTP method for request
Example

After deploying template function app, run

$ sls invoke -f hello -d '{"name": "Azure"}'

If you have a JSON object in a file, you could run

$ sls invoke -f hello -p data.json

If you have your service running locally (in another terminal), you can run:

$ sls invoke local -f hello -p data.json

If you configured your function app to run with APIM, you can run:

$ sls invoke apim -f hello -p data.json

Roll Back Your Function App

To roll back your function app to a previous deployment, simply select a timestamp of a previous deployment and use rollback command.

# List all deployments to know the timestamp for rollback
$ sls deploy list
Serverless:
-----------
Name: myFunctionApp-t1561479533
Timestamp: 1561479533
Datetime: 2019-06-25T16:18:53+00:00
-----------
Name: myFunctionApp-t1561479506
Timestamp: 1561479506
Datetime: 2019-06-25T16:18:26+00:00
-----------
Name: myFunctionApp-t1561479444
Timestamp: 1561479444
Datetime: 2019-06-25T16:17:24+00:00
-----------

# Rollback Function App to timestamp
$ sls rollback -t 1561479506

This will update the app code and infrastructure to the selected previous deployment.

For more details, check out our rollback docs.

Deleting Your Function App

If at any point you no longer need your service, you can run the following command to delete the resource group containing your Azure Function App and other depoloyed resources using:

$ sls remove

You will then be prompted to enter the full name of the resource group as an extra safety before deleting the entire resource group.

You can bypass this check by running:

$ sls remove --force

Creating or removing Azure Functions

To create a new Azure Function within your function app, run the following command from within your app's directory:

# -n or --name for name of new function
$ sls func add -n {functionName}

This will create a new handler file at the root of your project with the title {functionName}.js. It will also update serverless.yml to contain the new function.

To remove an existing Azure Function from your function app, run the following command from within your app's directory:

# -n or --name for name of function to remove
$ sls func remove -n {functionName}

This will remove the {functionName}.js handler and remove the function from serverless.yml

*Note: Add & remove currently only support HTTP triggered functions. For other triggers, you will need to update serverless.yml manually

Advanced Authentication

The getting started walkthrough illustrates the interactive login experience, which is recommended when getting started. However, for more robust use, a service principal is recommended for authentication.

Creating a Service Principal
  1. Install the Azure CLI

  2. Login via Azure CLI and set subscription

    # Login to Azure
    $ az login
    # Set Azure Subscription for which to create Service Principal
    $ az account set -s <subscription-id>
    
  3. Generate Service Principal for Azure Subscription

    # Create SP with unique name
    $ az ad sp create-for-rbac --name <my-unique-name>
    

    This will yield something like:

    {
      "appId": "<servicePrincipalId>",
      "displayName": "<name>",
      "name": "<name>",
      "password": "<password>",
      "tenant": "<tenantId>"
    }
    
  4. Set environment variables with values from above service principal

    Bash

    $ export AZURE_SUBSCRIPTION_ID='<subscriptionId (see above, step 2)>'
    $ export AZURE_TENANT_ID='<tenantId>'
    $ export AZURE_CLIENT_ID='<servicePrincipalId>'
    $ export AZURE_CLIENT_SECRET='<password>'
    

    Powershell

    $env:AZURE_SUBSCRIPTION_ID='<subscriptionId (see above, step 2)>'
    $env:AZURE_TENANT_ID='<tenantId>'
    $env:AZURE_CLIENT_ID='<servicePrincipalId>'
    $env:AZURE_CLIENT_SECRET='<password>'
    

Example Usage

Logging Verbosity

You can set the logging verbosity with the --verbose flag. If the --verbose flag is set with no value, logging will be as verbose as possible (debug mode). You can also provide a value with the flag to set the verbosity to a specific level:

  • --verbose error - Only error messages printed
  • --verbose warn - Only error and warning messages printed
  • --verbose info - Only error, warning and info messages printed
  • --verbose debug - All messages printed
Edit this page

Azure Functions - Quickstart

We try to keep this page up to date, but the most up to date documentation can be found in our README

Pre-requisites

  1. Node.js 8.x or above
  2. Serverless CLI v1.9.0+. You can run npm i -g serverless if you don't already have it.
  3. An Azure account. If you don't already have one, you can sign up for a free trial that includes $200 of free credit.

Create a new Azure Function App

# Create Azure Function App from template
# Templates include: azure-nodejs, azure-python, azure-dotnet
$ sls create -t azure-nodejs -p <appName>
# Move into project directory
$ cd <appName>
# Install dependencies (including this plugin)
$ npm install

The serverless.yml file contains the configuration for your service. For more details on its configuration, see the docs.

Running Function App Locally (offline plugin)

At the root of your project directory, run:

# Builds necessary function bindings files and starts the function app
$ sls offline

The offline process will generate a directory for each of your functions, which will contain a file titled function.json. This will contain a relative reference to your handler file & exported function from that file as long as they are referenced correctly in serverless.yml.

After the necessary files are generated, it will start the function app from within the same shell. For HTTP functions, the local URLs will be displayed in the console when the function app is initialized.

To build the files without spawning the process to start the function app, run:

$ sls offline build

To simply start the function app without building the files, run:

$ sls offline start

To clean up files generated from the build, run:

$ sls offline cleanup

To pass additional arguments to the spawned func host start process, add them as the option spawnargs (shortcut a). Example:

$ sls offline -a "--cors *"

This works for sls offline or sls offline start

Dry-Run Deployment

Before you deploy your new function app, you may want to double check the resources that will be created, their generated names and other basic configuration info. You can run:

# -d is short for --dryrun
$ sls deploy --dryrun

This will print out a basic summary of what your deployed service will look like.

For a more detailed look into the generated ARM template for your resource group, add the --arm (or -a) flag:

$ sls deploy --dryrun --arm

Deploy Your Function App

Deploy your new service to Azure! The first time you do this, you will be asked to authenticate with your Azure account, so the serverless CLI can manage Functions on your behalf. Simply follow the provided instructions, and the deployment will continue as soon as the authentication process is completed.

$ sls deploy

For more advanced deployment scenarios, see our deployment docs

Get a Summary of Your Deployed Function App

To see a basic summary of your application (same format as the dry-run summary above), run:

$ sls info

To look at the ARM template for the last successful deployment, add the --arm (or -a) flag:

$ sls info --arm

You can also get information services with different stages, regions or resource groups by passing any of those flags. Example:

$ sls info --stage prod --region westus2

Test Your Function App

Invoke your HTTP functions without ever leaving the CLI using:

$ sls invoke -f <functionName>
Invoke Options
  • -f or --function - Function to Invoke
  • -d or --data - Stringified JSON data to use as either query params or request body
  • -p or --path - Path to JSON file to use as either query params or request body
  • -m or --method - HTTP method for request
Example

After deploying template function app, run

$ sls invoke -f hello -d '{"name": "Azure"}'

If you have a JSON object in a file, you could run

$ sls invoke -f hello -p data.json

If you have your service running locally (in another terminal), you can run:

$ sls invoke local -f hello -p data.json

If you configured your function app to run with APIM, you can run:

$ sls invoke apim -f hello -p data.json

Roll Back Your Function App

To roll back your function app to a previous deployment, simply select a timestamp of a previous deployment and use rollback command.

# List all deployments to know the timestamp for rollback
$ sls deploy list
Serverless:
-----------
Name: myFunctionApp-t1561479533
Timestamp: 1561479533
Datetime: 2019-06-25T16:18:53+00:00
-----------
Name: myFunctionApp-t1561479506
Timestamp: 1561479506
Datetime: 2019-06-25T16:18:26+00:00
-----------
Name: myFunctionApp-t1561479444
Timestamp: 1561479444
Datetime: 2019-06-25T16:17:24+00:00
-----------

# Rollback Function App to timestamp
$ sls rollback -t 1561479506

This will update the app code and infrastructure to the selected previous deployment.

For more details, check out our rollback docs.

Deleting Your Function App

If at any point you no longer need your service, you can run the following command to delete the resource group containing your Azure Function App and other depoloyed resources using:

$ sls remove

You will then be prompted to enter the full name of the resource group as an extra safety before deleting the entire resource group.

You can bypass this check by running:

$ sls remove --force

Creating or removing Azure Functions

To create a new Azure Function within your function app, run the following command from within your app's directory:

# -n or --name for name of new function
$ sls func add -n {functionName}

This will create a new handler file at the root of your project with the title {functionName}.js. It will also update serverless.yml to contain the new function.

To remove an existing Azure Function from your function app, run the following command from within your app's directory:

# -n or --name for name of function to remove
$ sls func remove -n {functionName}

This will remove the {functionName}.js handler and remove the function from serverless.yml

*Note: Add & remove currently only support HTTP triggered functions. For other triggers, you will need to update serverless.yml manually

Advanced Authentication

The getting started walkthrough illustrates the interactive login experience, which is recommended when getting started. However, for more robust use, a service principal is recommended for authentication.

Creating a Service Principal
  1. Install the Azure CLI

  2. Login via Azure CLI and set subscription

    # Login to Azure
    $ az login
    # Set Azure Subscription for which to create Service Principal
    $ az account set -s <subscription-id>
    
  3. Generate Service Principal for Azure Subscription

    # Create SP with unique name
    $ az ad sp create-for-rbac --name <my-unique-name>
    

    This will yield something like:

    {
      "appId": "<servicePrincipalId>",
      "displayName": "<name>",
      "name": "<name>",
      "password": "<password>",
      "tenant": "<tenantId>"
    }
    
  4. Set environment variables with values from above service principal

    Bash

    $ export AZURE_SUBSCRIPTION_ID='<subscriptionId (see above, step 2)>'
    $ export AZURE_TENANT_ID='<tenantId>'
    $ export AZURE_CLIENT_ID='<servicePrincipalId>'
    $ export AZURE_CLIENT_SECRET='<password>'
    

    Powershell

    $env:AZURE_SUBSCRIPTION_ID='<subscriptionId (see above, step 2)>'
    $env:AZURE_TENANT_ID='<tenantId>'
    $env:AZURE_CLIENT_ID='<servicePrincipalId>'
    $env:AZURE_CLIENT_SECRET='<password>'
    

Example Usage

Logging Verbosity

You can set the logging verbosity with the --verbose flag. If the --verbose flag is set with no value, logging will be as verbose as possible (debug mode). You can also provide a value with the flag to set the verbosity to a specific level:

  • --verbose error - Only error messages printed
  • --verbose warn - Only error and warning messages printed
  • --verbose info - Only error, warning and info messages printed
  • --verbose debug - All messages printed