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

以下示例演示针对收到的每个 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;
    }
}

以下示例演示 function.json 文件中的一个 HTTP 触发器绑定以及使用该绑定的 C# 脚本 (.csx) 代码。The following example shows an HTTP trigger binding in a function.json file and C# script (.csx) code that uses the binding. 该函数针对收到的每个 HTTP 请求创建一个包含 CustomQueueMessage 对象有效负载的队列项。The function creates a queue item with a CustomQueueMessage object payload for each HTTP request received.

function.json 文件如下所示：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.

下面是可创建一条队列消息的 C# 脚本代码：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;
}

可以使用 ICollector 或 IAsyncCollector 参数一次性发送多条消息。You can send multiple messages at once by using an ICollector or IAsyncCollector parameter. 以下 C# 脚本代码发送多条消息，其中一条消息包含 HTTP 请求数据，另一条消息包含硬编码值：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" });
}

以下示例演示一个 Java 函数，该函数在受到 HTTP 请求触发时创建一个队列消息。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;
 }

在 Java 函数运行时库中，对其值将写入队列存储的参数使用 @QueueOutput 注释。In the Java functions runtime library, use the @QueueOutput annotation on parameters whose value would be written to Queue storage. 参数类型应为 OutputBinding<T>，其中 T 是 POJO 的任何本机 Java 类型。The parameter type should be OutputBinding<T>, where T is any native Java type of a POJO.

以下示例演示 function.json 文件中的一个 HTTP 触发器绑定以及使用该绑定的 JavaScript 函数。The following example shows an HTTP trigger binding in a function.json file and a JavaScript function that uses the binding. 该函数针对收到的每个 HTTP 请求创建一个队列项。The function creates a queue item for each HTTP request received.

function.json 文件如下所示：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.

JavaScript 代码如下所示：Here's the JavaScript code:

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

可以通过定义 myQueueItem 输出绑定的消息数组，一次性发送多条消息。You can send multiple messages at once by defining a message array for the myQueueItem output binding. 以下 JavaScript 代码针对收到的每个 HTTP 请求发送两条包含硬编码值的队列消息。The following JavaScript code sends two queue messages with hard-coded values for each HTTP request received.

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

以下代码示例演示了如何从 HTTP 触发的函数输出队列消息。The following code examples demonstrate how to output a queue message from an HTTP-triggered function. type 是 queue 的配置节定义了输出绑定。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"
    }
  ]
}

利用此绑定配置，PowerShell 函数可以使用 Push-OutputBinding 创建队列消息。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"
})

若要同时发送多条消息，请定义消息数组，并使用 Push-OutputBinding 向队列输出绑定发送消息。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"
})

在 C# 类库中，使用 QueueAttribute。In 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.

C# 脚本不支持特性。Attributes are not supported by C# Script.

使用 QueueOutput 注释可以将一条消息编写为函数的输出。The QueueOutput annotation allows you to write a message as the output of a function. 以下示例演示一个用于创建队列消息的 HTTP 触发的函数。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();
    }
}

与 QueueOutput 注释关联的参数类型化为 OutputBinding<T> 实例。The parameter associated with the QueueOutput annotation is typed as an OutputBinding<T> instance.

JavaScript 不支持特性。Attributes are not supported by JavaScript.

PowerShell 不支持特性。Attributes are not supported by PowerShell.

默认Default

使用 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:

• 可序列化为 JSON 的对象An object serializable as JSON
• string
• byte[]
• CloudQueueMessageCloudQueueMessage

如果在尝试绑定到 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:

• ICollector<T> 或 IAsyncCollector<T>ICollector<T> or IAsyncCollector<T>
• CloudQueueCloudQueue

其他类型Additional types

应用如果使用 5.0.0 版或更高版本的存储扩展，还可以使用用于 .NET 的 Azure SDK 中的类型。Apps using the 5.0.0 or higher version of the Storage extension may also use types from the Azure SDK for .NET. 此版本为了支持以下类型，删除了对旧的 CloudQueue 和 CloudQueueMessage 类型的支持：This version drops support for the legacy CloudQueue and CloudQueueMessage types in favor of the following types:

• QueueMessageQueueMessage
• 用于编写多个队列消息的 QueueClientQueueClient for writing multiple queue messages

有关使用这些类型的示例，请参阅扩展的 GitHub 存储库。For examples using these types, see the GitHub repository for the extension.

默认Default

使用 out T paramName 等方法参数写入一条队列消息。Write a single queue message by using a method parameter such as out T paramName. paramName 是在 function.json 的 name 属性中指定的值。The paramName is the value specified in the name property of function.json. 可以使用方法返回类型而不使用 out 参数，T 可为以下任何类型：You can use the method return type instead of an out parameter, and T can be any of the following types:

• 可序列化为 JSON 的对象An object serializable as JSON
• string
• byte[]
• CloudQueueMessageCloudQueueMessage

如果在尝试绑定到 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:

• ICollector<T> 或 IAsyncCollector<T>ICollector<T> or IAsyncCollector<T>
• CloudQueueCloudQueue

其他类型Additional types

应用如果使用 5.0.0 版或更高版本的存储扩展，还可以使用用于 .NET 的 Azure SDK 中的类型。Apps using the 5.0.0 or higher version of the Storage extension may also use types from the Azure SDK for .NET. 此版本为了支持以下类型，删除了对旧的 CloudQueue 和 CloudQueueMessage 类型的支持：This version drops support for the legacy CloudQueue and CloudQueueMessage types in favor of the following types:

• QueueMessageQueueMessage
• 用于编写多个队列消息的 QueueClientQueueClient for writing multiple queue messages

有关使用这些类型的示例，请参阅扩展的 GitHub 存储库。For examples using these types, see the GitHub repository for the extension.

可通过两个选项使用 QueueOutput 注释从函数输出队列消息：There are two options for outputting an Queue message 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 persisted as an Queue message.

• 命令性：若要显式设置消息值，请将注释应用于 OutputBinding<T> 类型的特定参数，其中 T 是 POJO 或任何本机 Java 类型。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. 使用此配置时，向 setValue 方法传递某值会将该值持久保存为队列消息。With this configuration, passing a value to the setValue method persists the value as an Queue message.

可通过 context.bindings.<NAME> 使用输出队列项，其中，<NAME> 与 function.json 中定义的名称相匹配。The output queue item is available via context.bindings.<NAME> where <NAME> matches the name defined in function.json. 可对队列项有效负载使用字符串或 JSON 可序列化对象。You can use a string or a JSON-serializable object for the queue item payload.

通过 Push-OutputBinding 可以输出到队列消息，你在其中传递的参数与 function.json 文件中绑定的 name 参数指定的名称匹配。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.