适用于 Azure Functions 的 Azure 队列存储输出绑定Azure Queue storage output bindings for Azure Functions

Azure Functions 可以通过设置输出绑定来创建新的 Azure 队列存储消息。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

以下示例演示针对收到的每个 HTTP 请求创建队列消息的C# 函数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;
    }
}

特性和注释Attributes and annotations

C# 类库中,使用 QueueAttributeIn C# class libraries, use the QueueAttribute.

该特性将应用到 out 参数,或应用到函数的返回值。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)
{
    ...
}

可以设置 Connection 属性来指定要使用的存储帐户,如以下示例中所示: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)
{
    ...
}

有关完整示例,请参阅输出示例For a complete example, see Output example.

可以使用 StorageAccount 特性在类、方法或参数级别指定存储帐户。You can use the StorageAccount attribute to specify the storage account at class, method, or parameter level. 有关详细信息,请参阅“触发器 - 特性”。For more information, see Trigger - attributes.

配置Configuration

下表解释了在 function.json** 文件和 Queue 特性中设置的绑定配置属性。The following table explains the binding configuration properties that you set in the function.json file and the Queue attribute.

function.json 属性function.json property Attribute 属性Attribute property 说明Description
typetype 不适用n/a 必须设置为 queueMust be set to queue. 在 Azure 门户中创建触发器时,会自动设置此属性。This property is set automatically when you create the trigger in the Azure portal.
directiondirection 不适用n/a 必须设置为 outMust be set to out. 在 Azure 门户中创建触发器时,会自动设置此属性。This property is set automatically when you create the trigger in the Azure portal.
namename 不适用n/a 表示函数代码中的队列的变量的名称。The name of the variable that represents the queue in function code. 设置为 $return 可引用函数返回值。Set to $return to reference the function return value.
queueNamequeueName QueueNameQueueName 队列的名称。The name of the queue.
连接connection ConnectionConnection 包含要用于此绑定的存储连接字符串的应用设置的名称。The name of an app setting that contains the Storage connection string to use for this binding. 如果应用设置名称以“AzureWebJobs”开始,则只能在此处指定该名称的余下部分。If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. 例如,如果将 connection 设置为“MyStorage”,Functions 运行时将会查找名为“MyStorage”的应用设置。For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "MyStorage." 如果将 connection 留空,函数运行时将使用名为 AzureWebJobsStorage 的应用设置中的默认存储连接字符串。If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

在本地进行开发时,应用设置将取 local.settings.json 文件的值。When you're developing locally, app settings go into the local.settings.json file.

使用情况Usage

使用 out T paramName 等方法参数写入一条队列消息。Write a single queue message by using a method parameter such as out T paramName. 可以使用方法返回类型而不使用 out 参数,T 可为以下任何类型:You can use the method return type instead of an out parameter, and T can be any of the following types:

如果在尝试绑定到 CloudQueueMessage 时出现错误消息,请确保引用正确的存储 SDK 版本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.

在 C# 和 C# 脚本中,可使用以下类型之一编写多条队列消息:In C# and C# script, write multiple queue messages by using one of the following types:

异常和返回代码Exceptions and return codes

绑定Binding 参考Reference
队列Queue 队列错误代码Queue Error Codes
Blob、表、队列Blob, Table, Queue 存储错误代码Storage Error Codes
Blob、表、队列Blob, Table, Queue 故障排除Troubleshooting

host.json 设置host.json settings

本部分介绍版本 2.x 及更高版本中可用于此绑定的全局配置设置。This section describes the global configuration settings available for this binding in versions 2.x and higher. 下面的示例 host.json 文件仅包含此绑定的 2.x 版及更高版本设置。The example host.json file below contains only the version 2.x+ settings for this binding. 若要详细了解 2.x 版及更高版本中的全局配置设置,请参阅 Azure Functions 的 host.json 参考For more information about global configuration settings in versions 2.x and beyond, see host.json reference for Azure Functions.

备注

有关 Functions 1.x 中 host.json 的参考,请参阅 Azure Functions 1.x 的 host.json 参考For a reference of host.json in Functions 1.x, see host.json reference for Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8
        }
    }
}
属性Property 默认Default 说明Description
maxPollingIntervalmaxPollingInterval 00:00:0100:00:01 队列轮询的最大间隔时间。The maximum interval between queue polls. 最小值为 00:00:00.100(100 毫秒),可递增至 00:01:00(1 分钟)。Minimum is 00:00:00.100 (100 ms) and increments up to 00:01:00 (1 min). 在 1.x 中,数据类型是毫秒,在 2.x 及更高版本中,数据类型是 TimeSpan。In 1.x the data type is milliseconds, and in 2.x and higher it is a TimeSpan.
visibilityTimeoutvisibilityTimeout 00:00:0000:00:00 消息处理失败时的重试间隔时间。The time interval between retries when processing of a message fails.
batchSizebatchSize 1616 Functions 运行时同时检索并并行处理的队列消息数。The number of queue messages that the Functions runtime retrieves simultaneously and processes in parallel. 当处理的数量下降到 newBatchThreshold 时,运行时可获取另一个批,并开始处理这些消息。When the number being processed gets down to the newBatchThreshold, the runtime gets another batch and starts processing those messages. 因此,每个函数处理的最大并发消息数是 batchSize 加上 newBatchThresholdSo the maximum number of concurrent messages being processed per function is batchSize plus newBatchThreshold. 此限制分别应用于各个队列触发的函数。This limit applies separately to each queue-triggered function.

如果要避免对队列上收到的消息并行执行,可以将 batchSize 设置为 1。If you want to avoid parallel execution for messages received on one queue, you can set batchSize to 1. 但是,只有在函数于单个虚拟机 (VM) 上运行时,此设置才可消除并发。However, this setting eliminates concurrency only so long as your function app runs on a single virtual machine (VM). 如果函数应用横向扩展到多个 VM,每个 VM 可运行每个队列触发的函数的一个实例。If the function app scales out to multiple VMs, each VM could run one instance of each queue-triggered function.

batchSize 的最大值为 32。The maximum batchSize is 32.
maxDequeueCountmaxDequeueCount 55 在将某个消息移到有害队列之前,尝试处理该消息的次数。The number of times to try processing a message before moving it to the poison queue.
newBatchThresholdnewBatchThreshold batchSize/2batchSize/2 只要同时处理的消息数下降到此数值,运行时即检索另一个批次。Whenever the number of messages being processed concurrently gets down to this number, the runtime retrieves another batch.

后续步骤Next steps