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.

Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

v2

The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the Python developer guide.

v1

The Python v1 programming model requires you to define bindings in a separate function.json file in the function folder. For more information, see the Python developer guide.

This article supports both programming models.

Important

The Python v2 programming model is currently in preview.

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.

In-process

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;
    }
}

Isolated process

[Function("QueueFunction")]
[QueueOutput("output-queue")]
public static string[] Run([QueueTrigger("input-queue")] Book myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Book name = {myQueueItem.Name}",
        $"Book ID = {myQueueItem.Id}"};
    var logger = context.GetLogger("QueueFunction");
    logger.LogInformation($"{messages[0]},{messages[1]}");

    // Queue Output messages
    return messages;
}

C# Script

The following example shows an HTTP trigger binding in a function.json file and C# script (.csx) code that uses the binding. The function creates a queue item with a CustomQueueMessage object payload 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": "$return",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

The configuration section explains these properties.

Here's C# script code that creates a single queue message:

public class CustomQueueMessage
{
    public string PersonName { get; set; }
    public string Title { get; set; }
}

public static CustomQueueMessage Run(CustomQueueMessage input, ILogger log)
{
    return input;
}

You can send multiple messages at once by using an ICollector or IAsyncCollector parameter. Here's C# script code that sends multiple messages, one with the HTTP request data and one with hard-coded values:

public static void Run(
    CustomQueueMessage input, 
    ICollector<CustomQueueMessage> myQueueItems, 
    ILogger log)
{
    myQueueItems.Add(input);
    myQueueItems.Add(new CustomQueueMessage { PersonName = "You", Title = "None" });
}

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. The example depends on whether you use the v1 or v2 Python programming model.

v2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueOutput1")
@app.route(route="message")
@app.queue_output(arg_name="msg", 
                  queue_name="<QUEUE_NAME>", 
                  connection="<CONNECTION_SETTING>")
def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('name')
    logging.info(input_msg)

    msg.set(input_msg)

    logging.info(f'name: {name}')
    return 'OK'

v1

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-process

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.

Isolated process

When running in an isolated worker process, you use the QueueOutputAttribute, which takes the name of the queue, as shown in the following example:

[Function("QueueFunction")]
[QueueOutput("output-queue")]
public static string[] Run([QueueTrigger("input-queue")] Book myQueueItem, FunctionContext context)

Only returned variables are supported when running in an isolated worker process. Output parameters can't be used.

C# script

C# script uses a function.json file for configuration instead of attributes.

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

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.

Decorators

Applies only to the Python v2 programming model.

For Python v2 functions defined using a decorator, the following properties on the queue_output:

Property	Description
arg_name	The name of the variable that represents the queue in function code.
queue_name	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.

For Python functions defined by using function.json, see the Configuration section.

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

Applies only to the Python v1 programming model.

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:

In-process

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

Isolated process

An isolated worker process class library compiled C# function runs in a process isolated from the runtime.

C# script

C# script is used primarily when creating C# functions in the Azure portal.

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

Extension 5.x+

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:

• An object serializable as JSON
• string
• byte[]
• QueueMessage

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:

• ICollector<T> or IAsyncCollector<T>
• QueueClient

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.

Extension 2.x+

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:

• An object serializable as JSON
• string
• byte[]
• CloudQueueMessage

If you try to bind to CloudQueueMessage and get an error message, make sure that you have a reference to the correct Storage SDK version.

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

• ICollector<T> or IAsyncCollector<T>
• CloudQueue

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.

Extension 5.x+

Isolated worker process currently only supports binding to string parameters.

Extension 2.x+

Isolated worker process currently only supports binding to string parameters.

Extension 5.x+

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:

• An object serializable as JSON
• string
• byte[]
• QueueMessage

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:

• ICollector<T> or IAsyncCollector<T>
• QueueClient

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

Extension 2.x+

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:

• An object serializable as JSON
• string
• byte[]
• CloudQueueMessage

If you try to bind to CloudQueueMessage and get an error message, make sure that you have a reference to the correct Storage SDK version.

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

• ICollector<T> or IAsyncCollector<T>
• CloudQueue

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 that specifies how the app should connect to Azure Queues. It may specify:

• The name of an application setting containing a connection string
• The name of a shared prefix for multiple application settings, together defining an identity-based connection.

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're 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 use an identity, you define settings under a common prefix that maps to the connection property in the trigger and binding configuration.

If you're 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're connecting, using the HTTPS scheme.	https://<storage_account_name>.queue.core.windows.net

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

Other 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

• Run a function as queue storage data changes (Trigger)