Azure Functions 的 Azure Blob 存储输入绑定Azure Blob storage input binding for Azure Functions

01/12/2021

通过输入绑定，可读取 blob 存储数据作为 Azure Functions 的输入。The input binding allows you to read blob storage data as input to an Azure Function.

若要了解设置和配置详细信息，请参阅概述。For information on setup and configuration details, see the overview.

示例Example

以下示例演示使用一个队列触发器和一个 blob 输入绑定的 C# 函数。The following example is a C# function that uses a queue trigger and an input blob binding. 队列消息包含该 blob 的名称，函数记录该 blob 的大小。The queue message contains the name of the blob, and the function logs the size of the blob.

[FunctionName("BlobInput")]
public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem,
    [Blob("samples-workitems/{queueTrigger}", FileAccess.Read)] Stream myBlob,
    ILogger log)
{
    log.LogInformation($"BlobInput processed blob\n Name:{myQueueItem} \n Size: {myBlob.Length} bytes");
}

以下示例演示 function.json 文件中的 blob 输入和输出绑定，以及使用这些绑定的 C# 脚本 (.csx) 代码。The following example shows blob input and output bindings in a function.json file and C# script (.csx) code that uses the bindings. 此函数创建文本 blob 的副本。The function makes a copy of a text blob. 该函数由包含要复制的 Blob 名称的队列消息触发。The function is triggered by a queue message that contains the name of the blob to copy. 新 Blob 名为 {originalblobname}-Copy。The new blob is named {originalblobname}-Copy.

在 function.json 文件中，queueTrigger 元数据属性用于指定 path 属性中的 Blob 名称：In the function.json file, the queueTrigger metadata property is used to specify the blob name in the path properties:

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnectionAppSetting",
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "myInputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in"
    },
    {
      "name": "myOutputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}-Copy",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false
}

配置部分解释了这些属性。The configuration section explains these properties.

C# 脚本代码如下所示：Here's the C# script code:

public static void Run(string myQueueItem, string myInputBlob, out string myOutputBlob, ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");
    myOutputBlob = myInputBlob;
}

本部分包含以下示例：This section contains the following examples:

HTTP 触发器，使用查询字符串查找 blob 名称HTTP trigger, look up blob name from query string
队列触发器，接收来自队列消息的 blob 名称Queue trigger, receive blob name from queue message

HTTP 触发器，使用查询字符串查找 blob 名称HTTP trigger, look up blob name from query string

下面的示例显示了一个 Java 函数，该函数使用 HttpTrigger 注释来接收包含 blob 存储容器中某个文件的名称的一个参数。The following example shows a Java function that uses the HttpTrigger annotation to receive a parameter containing the name of a file in a blob storage container. 然后，BlobInput 注释读取该文件并将其作为 byte[] 传递给该函数。The BlobInput annotation then reads the file and passes its contents to the function as a byte[].

  @FunctionName("getBlobSizeHttp")
  @StorageAccount("Storage_Account_Connection_String")
  public HttpResponseMessage blobSize(
    @HttpTrigger(name = "req", 
      methods = {HttpMethod.GET}, 
      authLevel = AuthorizationLevel.ANONYMOUS) 
    HttpRequestMessage<Optional<String>> request,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{Query.file}") 
    byte[] content,
    final ExecutionContext context) {
      // build HTTP response with size of requested blob
      return request.createResponseBuilder(HttpStatus.OK)
        .body("The size of \"" + request.getQueryParameters().get("file") + "\" is: " + content.length + " bytes")
        .build();
  }

队列触发器，接收来自队列消息的 blob 名称Queue trigger, receive blob name from queue message

下面的示例显示了一个 Java 函数，该函数使用 QueueTrigger 注释来接收包含 blob 存储容器中某个文件的名称的一个消息。The following example shows a Java function that uses the QueueTrigger annotation to receive a message containing the name of a file in a blob storage container. 然后，BlobInput 注释读取该文件并将其作为 byte[] 传递给该函数。The BlobInput annotation then reads the file and passes its contents to the function as a byte[].

  @FunctionName("getBlobSize")
  @StorageAccount("Storage_Account_Connection_String")
  public void blobSize(
    @QueueTrigger(
      name = "filename", 
      queueName = "myqueue-items-sample") 
    String filename,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{queueTrigger}") 
    byte[] content,
    final ExecutionContext context) {
      context.getLogger().info("The size of \"" + filename + "\" is: " + content.length + " bytes");
  }

在 Java 函数运行时库中，对其值将来自 Blob 的参数使用 @BlobInput 注释。In the Java functions runtime library, use the @BlobInput annotation on parameters whose value would come from a blob. 可以将此注释与本机 Java 类型、POJO 或使用了 Optional<T> 的可为 null 的值一起使用。This annotation can be used with native Java types, POJOs, or nullable values using Optional<T>.

下面的示例展示了 function.json 文件中的 blob 输入和输出绑定，以及使用这些绑定的 JavaScript 代码。The following example shows blob input and output bindings in a function.json file and JavaScript code that uses the bindings. 该函数创建 Blob 的副本。The function makes a copy of a blob. 该函数由包含要复制的 Blob 名称的队列消息触发。The function is triggered by a queue message that contains the name of the blob to copy. 新 Blob 名为 {originalblobname}-Copy。The new blob is named {originalblobname}-Copy.

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnectionAppSetting",
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "myInputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in"
    },
    {
      "name": "myOutputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}-Copy",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false
}

配置部分解释了这些属性。The configuration section explains these properties.

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

module.exports = function(context) {
    context.log('Node.js Queue trigger function processed', context.bindings.myQueueItem);
    context.bindings.myOutputBlob = context.bindings.myInputBlob;
    context.done();
};

以下示例显示了 function.json 文件中定义的 Blob 输入绑定，该绑定使传入的 blob 数据可供 PowerShell 函数使用。The following example shows a blob input binding, defined in the function.json file, which makes the incoming blob data available to the PowerShell function.

下面是 json 配置：Here's the json configuration:

{
  "bindings": [
    {
      "name": "InputBlob",
      "type": "blobTrigger",
      "direction": "in",
      "path": "source/{name}",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

下面是函数代码：Here's the function code:

# Input bindings are passed in via param block.
param([byte[]] $InputBlob, $TriggerMetadata)

Write-Host "PowerShell Blob trigger: Name: $($TriggerMetadata.Name) Size: $($InputBlob.Length) bytes"

特性和注释Attributes and annotations

在 C# 类库中，使用 BlobAttribute。In C# class libraries, use the BlobAttribute.

该特性的构造函数采用 Blob 的路径，以及一个表示读取或写入的 FileAccess 参数，如以下示例中所示：The attribute's constructor takes the path to the blob and a FileAccess parameter indicating read or write, as shown in the following example:

[FunctionName("BlobInput")]
public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem,
    [Blob("samples-workitems/{queueTrigger}", FileAccess.Read)] Stream myBlob,
    ILogger log)
{
    log.LogInformation($"BlobInput processed blob\n Name:{myQueueItem} \n Size: {myBlob.Length} bytes");
}

可以设置 Connection 属性来指定要使用的存储帐户，如以下示例中所示：You can set the Connection property to specify the storage account to use, as shown in the following example:

[FunctionName("BlobInput")]
public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem,
    [Blob("samples-workitems/{queueTrigger}", FileAccess.Read, Connection = "StorageConnectionAppSetting")] Stream myBlob,
    ILogger log)
{
    log.LogInformation($"BlobInput processed blob\n Name:{myQueueItem} \n Size: {myBlob.Length} bytes");
}

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

配置Configuration

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

function.json 属性function.json property	Attribute 属性Attribute property	说明Description
type type	不适用n/a	必须设置为 `blob`。Must be set to `blob`.
direction direction	不适用n/a	必须设置为 `in`。Must be set to `in`. 用法部分中已阐述异常。Exceptions are noted in the usage section.
name name	不适用n/a	表示函数代码中的 Blob 的变量的名称。The name of the variable that represents the blob in function code.
路径path	BlobPathBlobPath	Blob 的路径。The path to the blob.
连接 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 运行时会查找名为“AzureWebJobsMyStorage”的应用设置。For example, if you set `connection` to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage". 如果将 `connection` 留空，函数运行时将使用名为 `AzureWebJobsStorage` 的应用设置中的默认存储连接字符串。If you leave `connection` empty, the Functions runtime uses the default Storage connection string in the app setting that is named `AzureWebJobsStorage`. 连接字符串必须属于某个常规用途存储帐户，而不能属于仅限 Blob 的存储帐户。The connection string must be for a general-purpose storage account, not a blob-only storage account.
dataTypedataType	不适用n/a	对于动态类型化语言，指定基础数据类型。For dynamically typed languages, specifies the underlying data type. 可能的值为 `string`、`binary` 或 `stream`。Possible values are `string`, `binary`, or `stream`.
不适用n/a	访问Access	表示是要读取还是写入。Indicates whether you will be reading or writing.

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

使用情况Usage

可以将以下参数类型用于 blob 输入绑定：You can use the following parameter types for the blob input binding:

Stream
TextReader
string
Byte[]
CloudBlobContainer
CloudBlobDirectory
ICloudBlob¹ICloudBlob¹
CloudBlockBlob¹CloudBlockBlob¹
CloudPageBlob¹CloudPageBlob¹
CloudAppendBlob¹CloudAppendBlob¹

¹ function.json 中需有 "inout" 绑定 direction 或 C# 类库中需有 FileAccess.ReadWrite 。¹ Requires "inout" binding direction in function.json or FileAccess.ReadWrite in a C# class library.

如果在尝试绑定到某个存储 SDK 类型时出现错误消息，请确保引用正确的存储 SDK 版本。If you try to bind to one of the Storage SDK types and get an error message, make sure that you have a reference to the correct Storage SDK version.

由于整个 Blob 内容都会加载到内存中，因此，只有当 Blob 较小时才建议绑定到 string 或 Byte[]。Binding to string or Byte[] is only recommended if the blob size is small, as the entire blob contents are loaded into memory. 平时，最好使用 Stream 或 CloudBlockBlob 类型。Generally, it is preferable to use a Stream or CloudBlockBlob type. 有关详细信息，请参阅本文前文中的并发和内存使用情况。For more information, see Concurrency and memory usage earlier in this article.