Azure Functions 的 Azure Blob 存储输入绑定

项目
09/27/2022

通过输入绑定，可读取 blob 存储数据作为 Azure Functions 的输入。

若要了解设置和配置详细信息，请参阅概述。

示例

可以使用以下 C# 模式之一创建 C# 函数：

进程内类库：编译的 C# 函数，该函数在与 Functions 运行时相同的进程中运行。
独立进程类库：编译的 C# 函数，该函数在独立于运行时的进程中运行。支持在 .NET 5.0 上运行的 C# 函数需要独立的进程。
C# 脚本：主要在 Azure 门户中创建 C# 函数时使用。

以下示例演示使用一个队列触发器和一个 blob 输入绑定的 C# 函数。队列消息包含该 blob 的名称，函数记录该 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");
}

以下示例是一个 C# 函数，该函数在隔离的进程中运行，并将 blob 触发器与 blob 输入和 blob 输出 blob 绑定配合使用。在 test-samples-trigger 容器中创建 blob 时，会触发该函数。它从 test-samples-input 容器读取文本文件，并基于已触发文件的名称在输出容器中创建一个新的文本文件。

    public static class BlobFunction
    {
        [Function("BlobFunction")]
        [BlobOutput("test-samples-output/{name}-output.txt")]
        public static string Run(
            [BlobTrigger("test-samples-trigger/{name}")] string myTriggerItem,
            [BlobInput("test-samples-input/sample1.txt")] string myBlob,
            FunctionContext context)
        {
            var logger = context.GetLogger("BlobFunction");
            logger.LogInformation($"Triggered Item = {myTriggerItem}");
            logger.LogInformation($"Input Item = {myBlob}");

            // Blob Output
            return "blob-output content";
        }
    }
}

以下示例演示 function.json 文件中的 blob 输入和输出绑定，以及使用这些绑定的 C# 脚本 (.csx) 代码。此函数创建文本 blob 的副本。该函数由包含要复制的 Blob 名称的队列消息触发。新 Blob 名为 {originalblobname}-Copy。

在 function.json 文件中，queueTrigger 元数据属性用于指定 path 属性中的 Blob 名称：

{
  "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
}

配置部分解释了这些属性。

C# 脚本代码如下所示：

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

本部分包含以下示例：

HTTP 触发器，使用查询字符串查找 blob 名称
队列触发器，接收来自队列消息的 blob 名称

HTTP 触发器，使用查询字符串查找 blob 名称

下面的示例显示了一个 Java 函数，该函数使用 HttpTrigger 注释来接收包含 blob 存储容器中某个文件的名称的一个参数。然后，BlobInput 注释读取该文件并将其作为 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 名称

下面的示例显示了一个 Java 函数，该函数使用 QueueTrigger 注释来接收包含 blob 存储容器中某个文件的名称的一个消息。然后，BlobInput 注释读取该文件并将其作为 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 注释。可以将此注释与本机 Java 类型、POJO 或使用了 Optional<T> 的可为 null 的值一起使用。

下面的示例展示了 function.json 文件中的 blob 输入和输出绑定，以及使用这些绑定的 JavaScript 代码。该函数创建 Blob 的副本。该函数由包含要复制的 Blob 名称的队列消息触发。新 Blob 名为 {originalblobname}-Copy。

在 function.json 文件中，queueTrigger 元数据属性用于指定 path 属性中的 Blob 名称：

{
  "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
}

配置部分解释了这些属性。

JavaScript 代码如下所示：

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

以下示例显示了 function.json 文件中定义的 Blob 输入绑定，该绑定使传入的 Blob 数据可供 PowerShell 函数使用。

下面是 json 配置：

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

下面是函数代码：

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

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

下面的示例展示了 function.json 文件中的 blob 输入和输出绑定，以及使用这些绑定的 Python 代码。该函数创建 Blob 的副本。该函数由包含要复制的 Blob 名称的队列消息触发。新 Blob 名为 {originalblobname}-Copy。

在 function.json 文件中，queueTrigger 元数据属性用于指定 path 属性中的 Blob 名称：

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnectionAppSetting",
      "name": "queuemsg",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "inputblob",
      "type": "blob",
      "dataType": "binary",
      "path": "samples-workitems/{queueTrigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in"
    },
    {
      "name": "$return",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}-Copy",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false,
  "scriptFile": "__init__.py"
}

配置部分解释了这些属性。

dataType 属性确定使用的绑定。以下值可用于支持不同的绑定策略：

绑定值	默认	说明	示例
`string`	N	使用泛型绑定，并将输入类型强制转换为 `string`	`def main(input: str)`
`binary`	N	使用泛型绑定，并将输入 blob 强制转换为 `bytes` Python 对象	`def main(input: bytes)`

如果未在 function.json 上定义 dataType 属性，则默认值为 string。

下面是 Python 代码：

import logging
import azure.functions as func


# The input binding field inputblob can either be 'bytes' or 'str' depends
# on dataType in function.json, 'binary' or 'string'.
def main(queuemsg: func.QueueMessage, inputblob: bytes) -> bytes:
    logging.info(f'Python Queue trigger function processed {len(inputblob)} bytes')
    return inputblob

特性

进程内和独立进程 C# 库使用特性来定义函数。 C# 脚本改为使用 function.json 配置文件。

在 C# 类库中，使用采用以下参数的 BlobAttribute：

参数	说明
BlobPath	Blob 的路径。
Connection	指定如何连接到 Azure Blob 的应用设置或设置集合的名称。请参阅连接。
访问	表示是要读取还是写入。

以下示例演示该特性的构造函数采用 blob 路径的方式，以及一个表示输入绑定的读取的 FileAccess 参数：

[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 属性，但你也可以使用 StorageAccountAttribute 来指定存储帐户连接。如果需要使用一个不同于库中的其他函数的存储帐户，可以执行此操作。构造函数采用包含存储连接字符串的应用设置的名称。可以在参数、方法或类级别应用该特性。以下示例演示类级别和方法级别：

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

要使用的存储帐户按以下顺序确定：

触发器或绑定特性的 Connection 属性。
作为触发器或绑定特性应用到同一参数的 StorageAccount 特性。
应用到函数的 StorageAccount 特性。
应用到类的 StorageAccount 特性。
函数应用的默认存储帐户，在 AzureWebJobsStorage 应用程序设置中定义。

独立进程使用 BlobInputAttribute 特性定义输入绑定，该特性采用以下参数：

参数	说明
BlobPath	Blob 的路径。
Connection	指定如何连接到 Azure Blob 的应用设置或设置集合的名称。请参阅连接。

C# 脚本使用 function.json 文件进行配置，而不是特性。

下表解释了在 function.json 文件中设置的 C# 脚本的绑定配置属性。

function.json 属性	说明
type	必须设置为 `blob`。
direction	必须设置为 `in`。用法部分中已阐述异常。
name	表示函数代码中的 Blob 的变量的名称。
路径	Blob 的路径。
连接	指定如何连接到 Azure Blob 的应用设置或设置集合的名称。请参阅连接。
dataType	对于动态类型化语言，指定基础数据类型。可能的值为 `string`、`binary` 或 `stream`。有关更多详细信息，请参阅触发器和绑定概念。

在本地开发时，请将应用程序设置添加到 Values 集合的 local.settings.json 文件。

批注

使用 @BlobInput 特性可以访问触发函数的 blob。如果将字节数组与特性一起使用，请将 dataType 设置为 binary。有关详细信息，请参阅输入示例。

配置

下表解释了在 function.json 文件中设置的绑定配置属性。

function.json 属性	说明
type	必须设置为 `blob`。
direction	必须设置为 `in`。用法部分中已阐述异常。
name	表示函数代码中的 Blob 的变量的名称。
路径	Blob 的路径。
连接	指定如何连接到 Azure Blob 的应用设置或设置集合的名称。请参阅连接。
dataType	对于动态类型化语言，指定基础数据类型。可能的值为 `string`、`binary` 或 `stream`。有关更多详细信息，请参阅触发器和绑定概念。

有关完整示例的信息，请参阅示例部分。

使用情况

Blob 输入绑定的用法取决于扩展包版本，以及函数应用中使用的 C# 形式，可以是以下形式之一：

进程内类库是编译的 C# 函数，该函数在与 Functions 运行时相同的进程中运行。

选择一个版本以查看模式和版本的使用情况详细信息。

所有版本都支持以下参数类型：

Stream
TextReader
string
Byte[]

以下参数类型特定于扩展版本，需要具有 C# 类库的 FileAccess.ReadWrite：

有关使用这些类型的示例，请参阅扩展的 GitHub 存储库。通过 Azure.Storage.Blobs 迁移指南详细了解这些新类型的不同之处，以及如何迁移到这些类型。

还可使用 StorageAccountAttribute 指定要使用的存储帐户。如果需要使用一个不同于库中的其他函数的存储帐户，可以执行此操作。构造函数采用包含存储连接字符串的应用设置的名称。可以在参数、方法或类级别应用该特性。以下示例演示类级别和方法级别：

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

要使用的存储帐户按以下顺序确定：

BlobTrigger 特性的 Connection 属性。
作为 BlobTrigger 特性应用到同一参数的 StorageAccount 特性。
应用到函数的 StorageAccount 特性。
应用到类的 StorageAccount 特性。
函数应用的默认存储帐户，在 AzureWebJobsStorage 应用程序设置中定义。

所有版本都支持以下参数类型：

Stream
TextReader
string
Byte[]

以下参数类型特定于扩展版本，需要具有 C# 类库的 FileAccess.ReadWrite：

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

要使用的存储帐户按以下顺序确定：

BlobTrigger 特性的 Connection 属性。
作为 BlobTrigger 特性应用到同一参数的 StorageAccount 特性。
应用到函数的 StorageAccount 特性。
应用到类的 StorageAccount 特性。
函数应用的默认存储帐户，在 AzureWebJobsStorage 应用程序设置中定义。

仅当 blob 大小较小时才建议绑定到 string 或 Byte[]。我们推荐此做法，因为整个 blob 内容都会加载到内存中。对于大多数 blob，请使用 Stream 或 CloudBlockBlob 类型。有关详细信息，请参阅并发和内存使用情况。

如果尝试绑定到存储 SDK 类型之一时收到了错误消息，请确保已引用正确的存储 SDK 版本。

使用 @BlobInput 特性可以访问触发函数的 blob。如果将字节数组与特性一起使用，请将 dataType 设置为 binary。有关详细信息，请参阅输入示例。

使用 context.bindings.<NAME> 访问 blob 数据，其中 <NAME> 与 function.json 中定义的值匹配。

通过与 function.json 文件中绑定名称参数指定的名称匹配的字符串参数访问 Blob 数据。

通过类型为 InputStream 的参数访问 blob 数据。有关详细信息，请参阅输入示例。

连接

connection 属性是对环境配置的引用，它指定应用应如何连接到 Azure Blob。它可能指定：

包含连接字符串的应用程序设置的名称
多个应用程序设置的共享前缀的名称，共同定义基于标识的连接。

如果配置的值既是单个设置的完全匹配，也是其他设置的前缀匹配，则使用完全匹配。

连接字符串

要获取连接字符串，请执行管理存储帐户访问密钥中显示的步骤。连接字符串必须属于某个常规用途存储帐户，而不能属于Blob 存储帐户。

此连接字符串应存储在应用程序设置中，其名称与绑定配置的 connection 属性指定的值匹配。

如果应用设置名称以“AzureWebJobs”开始，则只能在此处指定该名称的余下部分。例如，如果将 connection 设置为“MyStorage”，Functions 运行时将会查找名为“AzureWebJobsMyStorage”的应用设置。如果将 connection 留空，Functions 运行时将使用应用设置中名为 AzureWebJobsStorage 的默认存储连接字符串。

基于标识的连接

如果使用 5.x 版或更高版本的扩展，则无需将连接字符串与机密一起使用，而是可以使应用使用 Azure Active Directory 标识。为此，需要定义公共前缀下的设置，该前缀映射到触发器和绑定配置中的 connection 属性。

如果将 connection 设置为“AzureWebJobsStorage”，请参阅使用标识连接到主机存储。对于所有其他连接，扩展需要以下属性：

属性	环境变量模板	说明	示例值
Blob 服务 URI	`<CONNECTION_NAME_PREFIX>__serviceUri`¹	要连接到的 Blob 服务的数据平面 URI，使用 HTTPS 方案。	https://<storage_account_name>.blob.core.chinacloudapi.cn

¹<CONNECTION_NAME_PREFIX>__blobServiceUri 可以用作别名。如果连接配置将由 Blob 触发器使用，则 blobServiceUri 还必须带有 queueServiceUri。请参阅下文。

如果要跨 Blob、队列和/或表使用总体连接配置，则无法使用 serviceUri 窗体。 URI 本身只能指定 Blob 服务。作为一种替代方案，可以为每个服务专门提供一个 URI，从而允许使用单个连接。如果这两个版本均提供，则将使用多服务窗体。若要为多个服务（而不是 <CONNECTION_NAME_PREFIX>__serviceUri）配置连接，请设置：

属性	环境变量模板	说明	示例值
Blob 服务 URI	`<CONNECTION_NAME_PREFIX>__blobServiceUri`	要连接到的 Blob 服务的数据平面 URI，使用 HTTPS 方案。	https://<storage_account_name>.blob.core.chinacloudapi.cn
队列服务 URI（Blob 触发器需要²）	`<CONNECTION_NAME_PREFIX>__queueServiceUri`	使用 HTTPS 方案的队列服务的数据平面 URI。仅 Blob 触发器需要该值。	https://<storage_account_name>.queue.core.chinacloudapi.cn

² Blob 触发器通过将有害 blob 写入队列来处理多次重试中出现的故障。在 serviceUri 窗体中，将使用 AzureWebJobsStorage 连接。但是，在指定 blobServiceUri 时，还必须为 queueServiceUri 提供队列服务 URI。建议使用与 Blob 服务相同的存储帐户中的服务。还需要通过分配存储队列数据参与者等角色来确保触发器可以在配置的队列服务中读取和写入消息。

可以设置其他属性来自定义连接。请参阅基于标识的连接的通用属性。

在 Azure Functions 服务中托管时，基于标识的连接将使用托管标识。默认情况下使用系统分配的标识，但可以使用 credential 和 clientID 属性来指定用户分配的标识。在其他上下文（如本地开发）中运行时，将改用开发人员标识，尽管可以进行自定义。请参阅使用基于标识的连接进行本地开发。

向标识授予权限

无论使用何种标识，都必须具有执行所需操作的权限。需要使用内置角色或者提供这些权限的自定义角色在 Azure RBAC 中分配角色。

重要

某些权限可能由并非所有上下文都需要的目标服务公开。尽可能遵循最低权限原则，仅授予标识所需的权限。例如，如果应用只需要从数据源进行读取即可，则使用仅具有读取权限的角色。分配一个也具有该服务写入权限的角色并不恰当，因为对于读取操作来说，写入是多余的权限。同样，你也希望确保角色分配的范围仅限于需要读取的资源。

你将需要创建一个角色分配，以便在运行时提供对 Blob 容器的访问权限。所有者等管理角色还不够。下表显示了在正常操作中使用 Blob 存储扩展时建议使用的内置角色。根据所编写的代码，应用程序可能需要具有其他权限。

绑定类型	内置角色示例
触发器	存储 Blob 数据所有者和存储队列数据参与者¹ 此外，还必须为 AzureWebJobsStorage 连接授予其他权限。²
输入绑定	存储 Blob 数据读者
输出绑定	存储 Blob 数据所有者

¹ Blob 触发器通过将有害 blob 写入到连接所指定的存储帐户上的队列来处理多次重试中出现的故障。

² AzureWebJobsStorage 连接在内部用于启用触发器的 blob 和队列。如果将其配置为使用基于标识的连接，则该连接将需要超出默认要求的其他权限。存储 Blob 数据所有者、存储队列数据参与者和存储帐户参与者角色涵盖了这些权限。若要了解详细信息，请参阅使用标识连接到主机存储。

Azure Functions 的 Azure Blob 存储输入绑定

示例

HTTP 触发器，使用查询字符串查找 blob 名称

队列触发器，接收来自队列消息的 blob 名称

特性

批注

配置

使用情况

连接

连接字符串

基于标识的连接

向标识授予权限

后续步骤