适用于 Azure Functions 的 Azure Blob 存储绑定概述

Azure Functions 通过触发器和绑定Azure 存储集成。 与 Blob 存储集成即可构建函数,用于响应 blob 数据中的更改以及读取和写入值。

操作 类型
在 blob 存储数据更改时运行函数 触发器
在函数中读取 blob 存储数据 输入绑定
允许函数写入 blob 存储数据 输出绑定

安装扩展

你安装的扩展 NuGet 包取决于你在函数应用中使用的 C# 模式:

函数在独立的 C# 工作进程中执行。 若要了解详细信息,请参阅有关在独立工作进程中运行 C# Azure Functions 的指南

扩展的功能因扩展版本而异:

此版本引入了使用标识而不是机密进行连接的功能。 有关使用托管标识配置函数应用的教程,请参阅使用基于标识的连接创建函数应用教程

此版本允许绑定到 Azure.Storage.Blobs 中的类型。 通过 Azure.Storage.Blobs 迁移指南详细了解这些新类型与 WindowsAzure.StorageMicrosoft.Azure.Storage 的不同之处以及如何迁移到这些类型。

通过安装 Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs NuGet 包(版本 5.x 或更高)将扩展添加到项目中。

使用 .NET CLI:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs

注意

Blob 存储、队列存储和表存储现在使用单独的扩展,并单独引用。 例如,若要在 .NET 隔离进程应用中同时使用 Blob 存储和队列存储触发器与绑定,应将以下包添加到项目:

Azure Cosmos DB for Table 扩展当前不支持独立进程。 如果你的应用需要使用 Azure 表,则必须使用 Microsoft.Azure.Functions.Worker.Extensions.Storage(版本 4.x)。 此包还有一个 5.x 版本,该版本仅引用 Blob 存储和队列存储的包。 在引用这些较新的拆分包时,请确保不要同时引用旧版组合存储包,否则会导致相同绑定的两种定义之间发生冲突。

如果要使用 F# 编写应用程序,则还必须将此扩展配置为应用的启动配置的一部分。 在对 ConfigureFunctionsWorkerDefaults()ConfigureFunctionsWebApplication() 的调用中,添加接受 IFunctionsWorkerApplication 参数的委托。 然后在该委托的正文中,在对象上调用 ConfigureBlobStorageExtension()

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureBlobStorageExtension() |> ignore
) |> ignore

安装捆绑包

Blob 存储绑定是在 host.json 项目文件中指定的扩展捆绑包的一部分。 你可能需要修改此捆绑包以更改绑定的版本,或者如果尚未安装捆绑包。 若要了解详细信息,请参阅扩展捆绑包

此版本引入了使用标识而不是机密进行连接的功能。 有关使用托管标识配置函数应用的教程,请参阅使用基于标识的连接创建函数应用教程

可以通过在 host.json 文件中添加或替换以下代码,从扩展捆绑包 v3 添加该扩展的这一版本:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

若要了解详细信息,请参阅更新扩展

绑定类型

.NET 支持的绑定类型取决于扩展版本和 C# 执行模式,可以是以下类型之一:

独立工作进程类库的已编译 C# 函数在独立于运行时的进程中运行。

请选择一个版本来查看模式和版本的绑定类型详细信息。

独立工作进程支持下表所示的参数类型。

Blob 触发器

Blob 触发器可以绑定到以下类型:

类型 说明
string Blob 内容即字符串。 在 blob 内容为简单文本时使用。
byte[] Blob 内容的字节数。
JSON 可序列化类型 当 blob 包含 JSON 数据时,Functions 会尝试将 JSON 数据反序列化为普通的旧 CLR 对象 (POCO) 类型。
(预览版1
Blob 内容的输入流。
BlobClient
BlockBlobClient
PageBlobClient
AppendBlobClient
BlobBaseClient
(预览版1
连接到 blob 的客户端。 这提供了对 blob 处理的充分控制,如果连接具有足够的权限,则可用于写回 blob。

1 若要使用这些类型,需要引用 Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 5.1.1-preview2 或更高版本以及 SDK 类型绑定的常见依赖项

blob 输入绑定

如果希望函数处理单个 blob,则可以将 blob 输入绑定绑定到以下类型:

类型 说明
string Blob 内容即字符串。 在 blob 内容为简单文本时使用。
byte[] Blob 内容的字节数。
JSON 可序列化类型 当 blob 包含 JSON 数据时,Functions 会尝试将 JSON 数据反序列化为普通的旧 CLR 对象 (POCO) 类型。
(预览版1
Blob 内容的输入流。
BlobClient
BlockBlobClient
PageBlobClient
AppendBlobClient
BlobBaseClient
(预览版1
连接到 blob 的客户端。 这提供了对 blob 处理的充分控制,如果连接具有足够的权限,则可用于写回 blob。

如果希望函数处理一个容器中的多个 blob,则可以将 blob 输入绑定绑定到以下类型:

类型 说明
T[]List<T>,其中 T 是单 blob 输出绑定类型之一 多个 blob 的数组或列表。 每个条目表示容器中的一个 blob。 还可以绑定到这些类型实施的任何接口,例如 IEnumerable<T>
BlobContainerClient (预览版1
连接到容器的客户端。 这提供了对容器处理的充分控制,如果连接具有足够的权限,则可用于写入容器。

BlobContainerClient 输入绑定的 BlobPath 配置当前需要 blob 名称。 仅提供容器名称是不够的。 可以使用占位符值,并且不会更改行为。 例如,设置 [BlobInput("samples-workitems/placeholder.txt")] BlobContainerClient containerClient 不考虑是否存在任何 placeholder.txt,并且客户端将使用整个“samples-workitems”容器。

1 若要使用这些类型,需要引用 Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 5.1.1-preview2 或更高版本以及 SDK 类型绑定的常见依赖项

blob 输出绑定

如果希望函数写入单个 blob,blob 输出绑定可以绑定到以下类型:

类型 说明
string Blob 内容即字符串。 在 blob 内容为简单文本时使用。
byte[] Blob 内容的字节数。
JSON 可序列化类型 表示 JSON blob 内容的对象。 函数尝试将普通的旧 CLR 对象 (POCO) 类型序列化为 JSON 数据。

如果希望函数写入多个 blob,blob 输出绑定可以绑定到以下类型:

类型 说明
T[],其中 T 是单 blob 输出绑定类型之一 包含多个 blob 的内容的数组。 每个条目表示一个 blob 的内容。

对于其他输出方案,请直接创建和使用 Azure.Storage.Blobs 中的类型。

host.json 设置

本部分介绍使用此绑定函数的函数应用程序配置设置。 这些设置仅在使用扩展版本 5.0.0 及更高版本时才适用。 下面的示例 host.json 文件仅包含此绑定的 2.x 版及更高版本设置。 若要详细了解版本 2.x 及更高版本中的函数应用程序配置设置,请参阅 Azure Functions 的 host.json 参考

注意

本部分不适用于 5.0.0 之前的扩展版本。 对于这些早期版本,没有任何适用于 Blob 的函数应用范围的配置设置。

{
    "version": "2.0",
    "extensions": {
        "blobs": {
            "maxDegreeOfParallelism": 4,
            "poisonBlobThreshold": 1
        }
    }
}
属性 默认 说明
maxDegreeOfParallelism 8 *(可用核心数) 给定函数应用中所有 blob 触发的函数允许的并发调用数(整数)。 允许的最小值为 1。
poisonBlobThreshold 5 在将某个消息移到有害队列之前,尝试处理该消息的整数次数。 允许的最小值为 1。

后续步骤