你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
Azure Functions 的 Azure Blob 存储输入绑定
通过输入绑定,可读取 blob 存储数据作为 Azure Functions 的输入。
若要了解设置和配置详细信息,请参阅概述。
重要
本文使用选项卡来支持多个版本的 Node.js 编程模型。 v4 模型已正式发布,旨在为 JavaScript 和 TypeScript 开发人员提供更为灵活和直观的体验。 有关 v4 模型工作原理的更多详细信息,请参阅 Azure Functions Node.js 开发人员指南。 要详细了解 v3 和 v4 之间的差异,请参阅迁移指南。
Azure Functions 支持两种 Python 编程模型。 定义绑定的方式取决于选择的编程模型。
使用 Python v2 编程模型,可以直接在 Python 函数代码中使用修饰器定义绑定。 有关详细信息,请参阅 Python 开发人员指南。
本文同时支持两个编程模型。
示例
可使用以下 C# 模式之一来创建 C# 函数:
- 独立辅助角色模型:编译的 C# 函数,该函数在独立于运行时的工作进程中运行。 需要独立工作进程才能支持在 LTS 和非 LTS 版 .NET 和 .NET Framework 上运行的 C# 函数。 独立工作进程函数的扩展使用
Microsoft.Azure.Functions.Worker.Extensions.*
命名空间。 - 进程内模型:编译的 C# 函数,该函数在与 Functions 运行时相同的进程中运行。 在此模型的变体中,可以使用 C# 脚本运行 Functions,该脚本主要用于 C# 门户编辑。 进程内函数的扩展使用
Microsoft.Azure.WebJobs.Extensions.*
命名空间。
重要
对进程内模型的支持将于 2026 年 11 月 10 日结束。 为获得完全支持,强烈建议将应用迁移到独立工作模型。
以下示例是一个 C# 函数,该函数在独立工作进程中运行,并将 blob 触发器与 blob 输入和 blob 输出 blob 绑定配合使用。 在 test-samples-trigger 容器中创建 blob 时,会触发该函数。 它从 test-samples-input 容器读取文本文件,并基于已触发文件的名称在输出容器中创建一个新的文本文件。
public static class BlobFunction
{
[Function(nameof(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}", myTriggerItem);
logger.LogInformation("Input Item = {myBlob}", myBlob);
// Blob Output
return "blob-output content";
}
}
}
本部分包含以下示例:
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 的值一起使用。
以下示例显示队列触发的 TypeScript 函数,该函数创建 blob 的副本。 该函数由包含要复制的 Blob 名称的队列消息触发。 新 Blob 名为 {originalblobname}-Copy。
import { app, input, InvocationContext, output } from '@azure/functions';
const blobInput = input.storageBlob({
path: 'samples-workitems/{queueTrigger}',
connection: 'MyStorageConnectionAppSetting',
});
const blobOutput = output.storageBlob({
path: 'samples-workitems/{queueTrigger}-Copy',
connection: 'MyStorageConnectionAppSetting',
});
export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<unknown> {
return context.extraInputs.get(blobInput);
}
app.storageQueue('storageQueueTrigger1', {
queueName: 'myqueue-items',
connection: 'MyStorageConnectionAppSetting',
extraInputs: [blobInput],
return: blobOutput,
handler: storageQueueTrigger1,
});
以下示例显示队列触发的 JavaScript 函数,该函数创建 blob 的副本。 该函数由包含要复制的 Blob 名称的队列消息触发。 新 Blob 名为 {originalblobname}-Copy。
const { app, input, output } = require('@azure/functions');
const blobInput = input.storageBlob({
path: 'samples-workitems/{queueTrigger}',
connection: 'MyStorageConnectionAppSetting',
});
const blobOutput = output.storageBlob({
path: 'samples-workitems/{queueTrigger}-Copy',
connection: 'MyStorageConnectionAppSetting',
});
app.storageQueue('storageQueueTrigger1', {
queueName: 'myqueue-items',
connection: 'MyStorageConnectionAppSetting',
extraInputs: [blobInput],
return: blobOutput,
handler: (queueItem, context) => {
return context.extraInputs.get(blobInput);
},
});
以下示例显示了 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"
此示例使用 SDK 类型直接访问 Blob 存储输入绑定提供的基础 BlobClient
对象:
import logging
import azure.functions as func
import azurefunctions.extensions.bindings.blob as blob
app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
@app.route(route="file")
@app.blob_input(
arg_name="client", path="PATH/TO/BLOB", connection="AzureWebJobsStorage"
)
def blob_input(req: func.HttpRequest, client: blob.BlobClient):
logging.info(
f"Python blob input function processed blob \n"
f"Properties: {client.get_blob_properties()}\n"
f"Blob content head: {client.download_blob().read(size=1)}"
)
return "ok"
有关使用其他 SDK 类型的示例,请参阅 ContainerClient
和 StorageStreamDownloader
示例。
若要了解详细信息,包括如何在项目中启用 SDK 类型绑定,请参阅 SDK 类型绑定。
代码可创建 Blob 的副本。
import logging
import azure.functions as func
app = func.FunctionApp()
@app.function_name(name="BlobOutput1")
@app.route(route="file")
@app.blob_input(arg_name="inputblob",
path="sample-workitems/test.txt",
connection="<BLOB_CONNECTION_SETTING>")
@app.blob_output(arg_name="outputblob",
path="newblob/test.txt",
connection="<BLOB_CONNECTION_SETTING>")
def main(req: func.HttpRequest, inputblob: str, outputblob: func.Out[str]):
logging.info(f'Python Queue trigger function processed {len(inputblob)} bytes')
outputblob.set(inputblob)
return "ok"
特性
进程内和独立工作进程 C# 库使用特性来定义函数。 C# 脚本改用 function.json 配置文件,如 C# 脚本指南中所述。
独立工作进程使用 BlobInputAttribute
属性定义输入绑定,该属性采用以下参数:
参数 | 说明 |
---|---|
BlobPath | Blob 的路径。 |
Connection | 指定如何连接到 Azure Blob 的应用设置或设置集合的名称。 请参阅连接。 |
在本地开发时,需要将应用程序设置添加到 Values
集合中的 local.settings.json 文件中。
修饰符
仅适用于 Python v2 编程模型。
对于使用修饰器定义的 Python v2 函数,blob_input
和 blob_output
上的以下属性可定义 Blob 存储触发器:
properties | 说明 |
---|---|
arg_name |
表示函数代码中的 Blob 的变量的名称。 |
path |
Blob 的路径。对于 blob_input 修饰器,它是 blob 读取。 对于 blob_output 修饰器,它是输入 Blob 的输出或副本。 |
connection |
存储帐户连接字符串。 |
data_type |
对于动态类型化语言,指定基础数据类型。 可能的值为 string 、binary 或 stream 。 有关更多详细信息,请参阅触发器和绑定概念。 |
对于使用 function.json 定义的 Python 函数,请参阅“配置”部分。
批注
使用 @BlobInput
特性可以访问触发函数的 blob。 如果将字节数组与特性一起使用,请将 dataType
设置为 binary
。 有关详细信息,请参阅输入示例。
配置
仅适用于 Python v1 编程模型。
下表解释了在 function.json 文件中设置的绑定配置属性。
“function.json”属性 | 说明 |
---|---|
type | 必须设置为 blob 。 |
direction | 必须设置为 in 。 用法部分中已阐述异常。 |
name | 表示函数代码中的 Blob 的变量的名称。 |
路径 | Blob 的路径。 |
连接 | 指定如何连接到 Azure Blob 的应用设置或设置集合的名称。 请参阅连接。 |
dataType | 对于动态类型化语言,指定基础数据类型。 可能的值为 string 、binary 或 stream 。 有关更多详细信息,请参阅触发器和绑定概念。 |
有关完整示例的信息,请参阅示例部分。
使用情况
Blob 输入支持的绑定类型取决于函数应用中使用的扩展包版本和 C# 形式。
如果希望函数处理单个 blob,则可以将 blob 输入绑定绑定到以下类型:
类型 | 说明 |
---|---|
string |
Blob 内容即字符串。 在 blob 内容为简单文本时使用。 |
byte[] |
Blob 内容的字节数。 |
JSON 可序列化类型 | 当 blob 包含 JSON 数据时,Functions 会尝试将 JSON 数据反序列化为普通的旧 CLR 对象 (POCO) 类型。 |
Stream1 | Blob 内容的输入流。 |
BlobClient1, BlockBlobClient1, PageBlobClient1, AppendBlobClient1, BlobBaseClient1 |
连接到 blob 的客户端。 此类型集提供了对 blob 处理的充分控制,如果连接具有足够的权限,则可用于写回 blob。 |
如果希望函数处理一个容器中的多个 blob,则可以将 blob 输入绑定绑定到以下类型:
类型 | 说明 |
---|---|
T[] 或 List<T> ,其中 T 是单 blob 输出绑定类型之一 |
多个 blob 的数组或列表。 每个条目表示容器中的一个 blob。 还可以绑定到这些类型实施的任何接口,例如 IEnumerable<T> 。 |
BlobContainerClient1 | 连接到容器的客户端。 此类型提供了对容器处理的充分控制,如果连接具有足够的权限,则可用于写入容器。 |
1 若要使用这些类型,需要引用 Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0 或更高版本以及 SDK 类型绑定的常见依赖项。
仅当 blob 大小较小时才建议绑定到 string
或 Byte[]
。 我们推荐此做法,因为整个 blob 内容都会加载到内存中。 对于大多数 blob,请使用 Stream
或 BlobClient
类型。 有关详细信息,请参阅并发和内存使用情况。
如果尝试绑定到某个存储 SDK 类型时收到了错误消息,请确保已引用正确的存储 SDK 版本。
还可使用 StorageAccountAttribute 指定要使用的存储帐户。 如果需要使用一个不同于库中的其他函数的存储帐户,可以执行此操作。 构造函数采用包含存储连接字符串的应用设置的名称。 可以在参数、方法或类级别应用该特性。 以下示例演示类级别和方法级别:
[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
[FunctionName("BlobTrigger")]
[StorageAccount("FunctionLevelStorageAppSetting")]
public static void Run( //...
{
....
}
要使用的存储帐户按以下顺序确定:
BlobTrigger
特性的Connection
属性。- 作为
BlobTrigger
特性应用到同一参数的StorageAccount
特性。 - 应用到函数的
StorageAccount
特性。 - 应用到类的
StorageAccount
特性。 - 函数应用的默认存储帐户,在
AzureWebJobsStorage
应用程序设置中定义。
使用 @BlobInput
特性可以访问触发函数的 blob。 如果将字节数组与特性一起使用,请将 dataType
设置为 binary
。 有关详细信息,请参阅输入示例。
通过与 function.json 文件中绑定名称参数指定的名称匹配的字符串参数访问 Blob 数据。
通过类型为 InputStream 的参数访问 blob 数据。 有关详细信息,请参阅输入示例。
Functions 还支持用于 Azure Blob 存储的 Python SDK 类型绑定,这样便可以使用以下基础 SDK 类型处理 Blob 数据:
重要
对 Python 的 SDK 类型支持目前为预览版,并且仅支持 Python v2 编程模型。 有关详细信息,请参阅 Python 中的 SDK 类型。
连接
connection
属性是对环境配置的引用,它指定应用应如何连接到 Azure Blob。 它可能指定:
如果配置的值既是单个设置的完全匹配,也是其他设置的前缀匹配,则使用完全匹配。
连接字符串
要获取连接字符串,请执行管理存储帐户访问密钥中显示的步骤。 连接字符串必须属于某个常规用途存储帐户,而不能属于Blob 存储帐户。
此连接字符串应存储在应用程序设置中,其名称与绑定配置的 connection
属性指定的值匹配。
如果应用设置名称以“AzureWebJobs”开始,则只能在此处指定该名称的余下部分。 例如,如果将 connection
设置为“MyStorage”,则 Functions 运行时会查找名为“AzureWebJobsMyStorage”的应用设置。 如果将 connection
留空,函数运行时将使用名为 AzureWebJobsStorage
的应用设置中的默认存储连接字符串。
基于标识的连接
如果使用的是 5.x 或更高版本的扩展(non-.NET 语言堆栈捆绑 3.x 或更高版本),则可以让应用使用Microsoft Entra 标识,而不是将连接字符串与机密一起使用。 要使用标识,需要定义公共前缀下的设置,该前缀映射到触发器和绑定配置中的 connection
属性。
如果将 connection
设置为“AzureWebJobsStorage”,请参阅使用标识连接到主机存储。 对于所有其他连接,扩展需要以下属性:
属性 | 环境变量模板 | 说明 | 示例值 |
---|---|---|---|
Blob 服务 URI | <CONNECTION_NAME_PREFIX>__serviceUri 1 |
要连接到的 Blob 服务的数据平面 URI,使用 HTTPS 方案。 | https://<storage_account_name>.blob.core.windows.net |
1 <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.windows.net |
队列服务 URI(Blob 触发器需要2) | <CONNECTION_NAME_PREFIX>__queueServiceUri |
使用 HTTPS 方案的队列服务的数据平面 URI。 仅 Blob 触发器需要该值。 | https://<storage_account_name>.queue.core.windows.net |
2 Blob 触发器通过将有害 blob 写入队列来处理多次重试中出现的故障。 在 serviceUri
窗体中,将使用 AzureWebJobsStorage
连接。 但是,在指定 blobServiceUri
时,还必须为 queueServiceUri
提供队列服务 URI。 建议使用与 Blob 服务相同的存储帐户中的服务。 还需要通过分配存储队列数据参与者等角色来确保触发器可以在配置的队列服务中读取和写入消息。
可以设置其他属性来自定义连接。 请参阅基于标识的连接的通用属性。
在 Azure Functions 服务中托管时,基于标识的连接将使用托管标识。 默认情况下使用系统分配的标识,但可以使用 credential
和 clientID
属性来指定用户分配的标识。 请注意,不支持为用户分配的标识配置资源 ID。 在其他上下文(如本地开发)中运行时,将改用开发人员标识,尽管可以进行自定义。 请参阅使用基于标识的连接进行本地开发。
向标识授予权限
无论使用何种标识,都必须具有执行所需操作的权限。 对于大多数 Azure 服务,这意味着你需要使用内置角色或者提供这些权限的自定义角色在 Azure RBAC 中分配角色。
重要
某些权限可能由并非所有上下文都需要的目标服务公开。 尽可能遵循最低权限原则,仅授予标识所需的权限。 例如,如果应用只需要从数据源进行读取即可,则使用仅具有读取权限的角色。 分配一个也具有该服务写入权限的角色并不恰当,因为对于读取操作来说,写入是多余的权限。 同样,你也希望确保角色分配的范围仅限于需要读取的资源。
你需要创建一个角色分配,以在运行时提供对 Blob 容器的访问权限。 所有者等管理角色还不够。 下表显示了在正常操作中使用 Blob 存储扩展时建议使用的内置角色。 根据所编写的代码,应用程序可能需要进一步的权限。
绑定类型 | 内置角色示例 |
---|---|
触发器 | 存储 Blob 数据所有者和存储队列数据参与者1 此外,还必须向 AzureWebJobsStorage 连接授予额外的权限。2 |
输入绑定 | 存储 Blob 数据读者 |
输出绑定 | 存储 Blob 数据所有者 |
1 Blob 触发器通过将有害 blob 写入到连接所指定的存储帐户上的队列来处理多次重试中出现的故障。
2 AzureWebJobsStorage 连接在内部用于启用触发器的 blob 和队列。 如果将其配置为使用基于标识的连接,则该连接将需要超出默认要求的其他权限。 存储 Blob 数据所有者、存储队列数据参与者和存储帐户参与者角色涵盖了所需的权限。 若要了解详细信息,请参阅使用标识连接到主机存储。