Azure Queue storage output bindings for Azure Functions

Azure Functions can create new Azure Queue storage messages by setting up an output binding.

For information on setup and configuration details, see the overview.

Example

A C# function can be created using one of the following C# modes:

  • In-process class library: compiled C# function that runs in the same process as the Functions runtime.
  • Isolated worker process class library: compiled C# function that runs in a worker process that is isolated from the runtime. Isolated worker process is required to support C# functions running on non-LTS versions .NET and the .NET Framework.
  • C# script: used primarily when creating C# functions in the Azure portal.

The following example shows a C# function that creates a queue message for each HTTP request received.

[StorageAccount("MyStorageConnectionAppSetting")]
public static class QueueFunctions
{
    [FunctionName("QueueOutput")]
    [return: Queue("myqueue-items")]
    public static string QueueOutput([HttpTrigger] dynamic input,  ILogger log)
    {
        log.LogInformation($"C# function processed: {input.Text}");
        return input.Text;
    }
}

The following example shows a Java function that creates a queue message for when triggered by an HTTP request.

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "MyStorageConnectionAppSetting")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding<String> result) {
       result.setValue(message + " has been added.");
       return message;
 }

In the Java functions runtime library, use the @QueueOutput annotation on parameters whose value would be written to Queue storage. The parameter type should be OutputBinding<T>, where T is any native Java type of a POJO.

The following example shows an HTTP trigger binding in a function.json file and a JavaScript function that uses the binding. The function creates a queue item for each HTTP request received.

Here's the function.json file:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "myQueueItem",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

The configuration section explains these properties.

Here's the JavaScript code:

module.exports = async function (context, input) {
    context.bindings.myQueueItem = input.body;
};

You can send multiple messages at once by defining a message array for the myQueueItem output binding. The following JavaScript code sends two queue messages with hard-coded values for each HTTP request received.

module.exports = async function(context) {
    context.bindings.myQueueItem = ["message 1","message 2"];
};

The following code examples demonstrate how to output a queue message from an HTTP-triggered function. The configuration section with the type of queue defines the output binding.

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "Msg",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Using this binding configuration, a PowerShell function can create a queue message using Push-OutputBinding. In this example, a message is created from a query string or body parameter.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = $Request.Query.Message
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

To send multiple messages at once, define a message array and use Push-OutputBinding to send messages to the Queue output binding.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = @("message1", "message2")
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

The following example demonstrates how to output single and multiple values to storage queues. The configuration needed for function.json is the same either way.

A Storage queue binding is defined in function.json where type is set to queue.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "msg",
      "queueName": "outqueue",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

To set an individual message on the queue, you pass a single value to the set method.

import azure.functions as func

def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

    input_msg = req.params.get('message')

    msg.set(input_msg)

    return 'OK'

To create multiple messages on the queue, declare a parameter as the appropriate list type and pass an array of values (that match the list type) to the set method.

import azure.functions as func
import typing

def main(req: func.HttpRequest, msg: func.Out[typing.List[str]]) -> func.HttpResponse:

    msg.set(['one', 'two'])

    return 'OK'

Attributes

The attribute that defines an output binding in C# libraries depends on the mode in which the C# class library runs. C# script instead uses a function.json configuration file.

In C# class libraries, use the QueueAttribute.

The attribute applies to an out parameter or the return value of the function. The attribute's constructor takes the name of the queue, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

You can set the Connection property to specify the storage account to use, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items", Connection = "StorageConnectionAppSetting")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

You can use the StorageAccount attribute to specify the storage account at class, method, or parameter level. For more information, see Trigger - attributes.

Annotations

The QueueOutput annotation allows you to write a message as the output of a function. The following example shows an HTTP-triggered function that creates a queue message.

package com.function;
import java.util.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

public class HttpTriggerQueueOutput {
    @FunctionName("HttpTriggerQueueOutput")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION) HttpRequestMessage<Optional<String>> request,
            @QueueOutput(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") OutputBinding<String> message,
            final ExecutionContext context) {

        message.setValue(request.getQueryParameters().get("name"));
        return request.createResponseBuilder(HttpStatus.OK).body("Done").build();
    }
}
Property Description
name Declares the parameter name in the function signature. When the function is triggered, this parameter's value has the contents of the queue message.
queueName Declares the queue name in the storage account.
connection Points to the storage account connection string.

The parameter associated with the QueueOutput annotation is typed as an OutputBinding<T> instance.

Configuration

The following table explains the binding configuration properties that you set in the function.json file.

function.json property Description
type Must be set to queue. This property is set automatically when you create the trigger in the Azure portal.
direction Must be set to out. This property is set automatically when you create the trigger in the Azure portal.
name The name of the variable that represents the queue in function code. Set to $return to reference the function return value.
queueName The name of the queue.
connection The name of an app setting or setting collection that specifies how to connect to Azure Queues. See Connections.

When you're developing locally, add your application settings in the local.settings.json file in the Values collection.

See the Example section for complete examples.

Usage

The usage of the Queue output binding depends on the extension package version and the C# modality used in your function app, which can be one of the following:

An in-process class library is a compiled C# function runs in the same process as the Functions runtime.

Choose a version to see usage details for the mode and version.

Write a single queue message by using a method parameter such as out T paramName. You can use the method return type instead of an out parameter, and T can be any of the following types:

For examples using these types, see the GitHub repository for the extension.

You can write multiple messages to the queue by using one of the following types:

For examples using QueueMessage and QueueClient, see the GitHub repository for the extension.

While the attribute takes a Connection property, you can also use the StorageAccountAttribute to specify a storage account connection. You can do this when you need to use a different storage account than other functions in the library. The constructor takes the name of an app setting that contains a storage connection string. The attribute can be applied at the parameter, method, or class level. The following example shows class level and method level:

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

The storage account to use is determined in the following order:

  • The trigger or binding attribute's Connection property.
  • The StorageAccount attribute applied to the same parameter as the trigger or binding attribute.
  • The StorageAccount attribute applied to the function.
  • The StorageAccount attribute applied to the class.
  • The default storage account for the function app, which is defined in the AzureWebJobsStorage application setting.

There are two options for writing to a queue from a function by using the QueueOutput annotation:

  • Return value: By applying the annotation to the function itself, the return value of the function is written to the queue.

  • Imperative: To explicitly set the message value, apply the annotation to a specific parameter of the type OutputBinding<T>, where T is a POJO or any native Java type. With this configuration, passing a value to the setValue method writes the value to the queue.

The output queue item is available via context.bindings.<NAME> where <NAME> matches the name defined in function.json. You can use a string or a JSON-serializable object for the queue item payload.

Output to the queue message is available via Push-OutputBinding where you pass arguments that match the name designated by binding's name parameter in the function.json file.

There are two options for writing from your function to the configured queue:

  • Return value: Set the name property in function.json to $return. With this configuration, the function's return value is persisted as a Queue storage message.

  • Imperative: Pass a value to the set method of the parameter declared as an Out type. The value passed to set is persisted as a Queue storage message.

Connections

The connection property is a reference to environment configuration which specifies how the app should connect to Azure Queues. It may specify:

If the configured value is both an exact match for a single setting and a prefix match for other settings, the exact match is used.

Connection string

To obtain a connection string, follow the steps shown at Manage storage account access keys.

This connection string should be stored in an application setting with a name matching the value specified by the connection property of the binding configuration.

If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

Identity-based connections

If you are using version 5.x or higher of the extension, instead of using a connection string with a secret, you can have the app use an Azure Active Directory identity. To do this, you would define settings under a common prefix which maps to the connection property in the trigger and binding configuration.

If you are setting connection to "AzureWebJobsStorage", see Connecting to host storage with an identity. For all other connections, the extension requires the following properties:

Property Environment variable template Description Example value
Queue Service URI <CONNECTION_NAME_PREFIX>__queueServiceUri1 The data plane URI of the queue service to which you are connecting, using the HTTPS scheme. https://<storage_account_name>.queue.core.windows.net

1 <CONNECTION_NAME_PREFIX>__serviceUri can be used as an alias. If both forms are provided, the queueServiceUri form will be used. The serviceUri form cannot be used when the overall connection configuration is to be used across blobs, queues, and/or tables.

Additional properties may be set to customize the connection. See Common properties for identity-based connections.

When hosted in the Azure Functions service, identity-based connections use a managed identity. The system-assigned identity is used by default, although a user-assigned identity can be specified with the credential and clientID properties. Note that configuring a user-assigned identity with a resource ID is not supported. When run in other contexts, such as local development, your developer identity is used instead, although this can be customized. See Local development with identity-based connections.

Grant permission to the identity

Whatever identity is being used must have permissions to perform the intended actions. For most Azure services, this means you need to assign a role in Azure RBAC, using either built-in or custom roles which provide those permissions.

Important

Some permissions might be exposed by the target service that are not necessary for all contexts. Where possible, adhere to the principle of least privilege, granting the identity only required privileges. For example, if the app only needs to be able to read from a data source, use a role that only has permission to read. It would be inappropriate to assign a role that also allows writing to that service, as this would be excessive permission for a read operation. Similarly, you would want to ensure the role assignment is scoped only over the resources that need to be read.

You will need to create a role assignment that provides access to your queue at runtime. Management roles like Owner are not sufficient. The following table shows built-in roles that are recommended when using the Queue Storage extension in normal operation. Your application may require additional permissions based on the code you write.

Binding type Example built-in roles
Trigger Storage Queue Data Reader, Storage Queue Data Message Processor
Output binding Storage Queue Data Contributor, Storage Queue Data Message Sender

Exceptions and return codes

Binding Reference
Queue Queue Error Codes
Blob, Table, Queue Storage Error Codes
Blob, Table, Queue Troubleshooting

Next steps