检测到新的或更新的 Blob 时,Blob 存储触发器会启动某个函数。 Blob 内容以函数输入的形式提供。
Azure Blob 存储触发器需要使用常规用途存储帐户。 还支持具有分层命名空间的存储 V2 帐户。 若要使用仅限 Blob 的帐户,或者,如果应用程序有特殊需求,请查看使用此触发器的替代方法。
若要了解设置和配置详细信息,请参阅概述。
轮询
轮询在检查日志和运行定期容器扫描之间起到混合作用。 每次以 10,000 个为一组扫描 Blob,并在间隔之间使用继续标记。
Warning: 此外,将“尽力”创建存储日志。 不保证捕获所有事件。 在某些情况下可能会遗漏某些日志。
如果需要更快或更可靠的 blob 处理,在创建 blob 时,请考虑创建队列消息。 然后,使用队列触发器而不是 Blob 触发器来处理 Blob。 另一个选项是使用事件网格;请参阅教程使用事件网格自动调整上传图像的大小。
备选方法
事件网格触发器
事件网格触发器还为 blob 事件提供内置支持。 以下方案请使用事件网格而不是 Blob 存储触发器:
-
仅限 Blob 的存储帐户:仅限 Blob 的存储帐户适用于 Blob 输入和输出绑定,但不适用于 Blob 触发器。
-
大规模:大规模可以宽松地定义为包含 100,000 个以上的 Blob 的容器,或者定义为每秒进行 100 个以上 Blob 更新的存储帐户。
-
最大程度地降低延迟:如果函数应用基于消耗计划,则当函数应用处于空闲状态时,处理新 Blob 会出现长达 10 分钟的延迟。 若要避免此延迟,可以切换到启用了 Always On 的应用服务计划。 还可以为 Blob 存储帐户使用事件网格触发器。 有关示例,请参阅事件网格教程。
请参阅事件网格示例的使用事件网格重试图像大小教程。
队列存储触发器
处理 blob 的另一种方法是编写对应于正在创建或修改的 blob 的队列消息,然后使用队列存储触发器开始处理。
示例
C#
以下示例演示在 samples-workitems 容器中添加或更新 blob 时写入日志的 C# 函数。
[FunctionName("BlobTriggerCSharp")]
public static void Run([BlobTrigger("samples-workitems/{name}")] Stream myBlob, string name, ILogger log)
{
log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name} \n Size: {myBlob.Length} Bytes");
}
blob 触发器路径 samples-workitems/{name} 中的字符串 {name} 会创建一个绑定表达式,可以在函数代码中使用它来访问触发 blob 的文件名。 有关详细信息,请参阅本文下文中的 Blob 名称模式。
有关 BlobTrigger 属性的详细信息,请参阅属性和注释。
C# 脚本
以下示例显示了 function.json 文件中的一个 blob 触发器绑定以及使用该绑定的代码。 在 samples-workitems 容器中添加或更新 Blob 时,该函数会写入一条日志。
下面是 function.json 文件中的绑定数据:
{
"disabled": false,
"bindings": [
{
"name": "myBlob",
"type": "blobTrigger",
"direction": "in",
"path": "samples-workitems/{name}",
"connection":"MyStorageAccountAppSetting"
}
]
}
blob 触发器路径 samples-workitems/{name} 中的字符串 {name} 会创建一个绑定表达式,可以在函数代码中使用它来访问触发 blob 的文件名。 有关详细信息,请参阅本文下文中的 Blob 名称模式。
有关 function.json 文件属性的详细信息,请参阅解释了这些属性的 配置部分。
下面是绑定到 Stream 的 C# 脚本代码:
public static void Run(Stream myBlob, string name, ILogger log)
{
log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name} \n Size: {myBlob.Length} Bytes");
}
下面是绑定到 CloudBlockBlob 的 C# 脚本代码:
#r "Microsoft.WindowsAzure.Storage"
using Microsoft.WindowsAzure.Storage.Blob;
public static void Run(CloudBlockBlob myBlob, string name, ILogger log)
{
log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name}\nURI:{myBlob.StorageUri}");
}
Java
在 myblob 容器中添加或更新 Blob 时,该函数会写入一条日志。
@FunctionName("blobprocessor")
public void run(
@BlobTrigger(name = "file",
dataType = "binary",
path = "myblob/{name}",
connection = "MyStorageAccountAppSetting") byte[] content,
@BindingName("name") String filename,
final ExecutionContext context
) {
context.getLogger().info("Name: " + filename + " Size: " + content.length + " bytes");
}
JavaScript
以下示例显示了 function.json 文件中的一个 Blob 触发器绑定以及使用该绑定的 JavaScript 代码。 在 samples-workitems 容器中添加或更新 Blob 时,该函数会写入日志。
function.json 文件如下所示:
{
"disabled": false,
"bindings": [
{
"name": "myBlob",
"type": "blobTrigger",
"direction": "in",
"path": "samples-workitems/{name}",
"connection":"MyStorageAccountAppSetting"
}
]
}
blob 触发器路径 samples-workitems/{name} 中的字符串 {name} 会创建一个绑定表达式,可以在函数代码中使用它来访问触发 blob 的文件名。 有关详细信息,请参阅本文下文中的 Blob 名称模式。
有关 function.json 文件属性的详细信息,请参阅解释了这些属性的 配置部分。
JavaScript 代码如下所示:
module.exports = function(context) {
context.log('Node.js Blob trigger function processed', context.bindings.myBlob);
context.done();
};
PowerShell
下面的示例演示如何创建在将文件添加到 source blob 存储容器时运行的函数。
函数配置文件 (function.json) 包含一个绑定,其 type 为 blobTrigger 且 direction 设置为 in。
{
"bindings": [
{
"name": "InputBlob",
"type": "blobTrigger",
"direction": "in",
"path": "source/{name}",
"connection": "MyStorageAccountConnectionString"
}
]
}
下面是 run.ps1 文件的关联代码。
param([byte[]] $InputBlob, $TriggerMetadata)
Write-Host "PowerShell Blob trigger: Name: $($TriggerMetadata.Name) Size: $($InputBlob.Length) bytes"
Python
以下示例显示了 function.json 文件中的一个 Blob 触发器绑定以及使用该绑定的 Python 代码。 在 samples-workitems 容器中添加或更新 Blob 时,该函数会写入一条日志。
function.json 文件如下所示:
{
"scriptFile": "__init__.py",
"disabled": false,
"bindings": [
{
"name": "myblob",
"type": "blobTrigger",
"direction": "in",
"path": "samples-workitems/{name}",
"connection":"MyStorageAccountAppSetting"
}
]
}
blob 触发器路径 samples-workitems/{name} 中的字符串 {name} 会创建一个绑定表达式,可以在函数代码中使用它来访问触发 blob 的文件名。 有关详细信息,请参阅本文下文中的 Blob 名称模式。
有关 function.json 文件属性的详细信息,请参阅解释了这些属性的 配置部分。
下面是 Python 代码:
import logging
import azure.functions as func
def main(myblob: func.InputStream):
logging.info('Python Blob trigger function processed %s', myblob.name)
特性和注释
C#
对于 C# 类库,请使用以下属性来配置 blob 触发器:
-
该特性的构造函数采用一个表示要监视的容器的路径字符串,并选择性地采用某种 Blob 名称模式。 下面是一个示例:
[FunctionName("ResizeImage")] public static void Run( [BlobTrigger("sample-images/{name}")] Stream image, [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageSmall) { .... }可以设置
Connection属性来指定要使用的存储帐户,如以下示例中所示:[FunctionName("ResizeImage")] public static void Run( [BlobTrigger("sample-images/{name}", Connection = "StorageConnectionAppSetting")] Stream image, [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageSmall) { .... }有关完整示例,请参阅触发器示例。
-
提供另一种方式来指定要使用的存储帐户。 构造函数采用包含存储连接字符串的应用设置的名称。 可以在参数、方法或类级别应用该特性。 以下示例演示类级别和方法级别:
[StorageAccount("ClassLevelStorageAppSetting")] public static class AzureFunctions { [FunctionName("BlobTrigger")] [StorageAccount("FunctionLevelStorageAppSetting")] public static void Run( //... { .... }
要使用的存储帐户按以下顺序确定:
BlobTrigger特性的Connection属性。- 作为
BlobTrigger特性应用到同一参数的StorageAccount特性。 - 应用到函数的
StorageAccount特性。 - 应用到类的
StorageAccount特性。 - 函数应用的默认存储帐户(“AzureWebJobsStorage”应用设置)。
C# 脚本
C# 脚本不支持特性。
Java
@BlobTrigger 特性用于授予对触发函数的 blob 的访问权限。 有关详细信息,请参阅触发器示例。
JavaScript
JavaScript 不支持特性。
PowerShell
PowerShell 不支持特性。
Python
Python 不支持特性。
配置
下表解释了在 function.json 文件和 BlobTrigger 特性中设置的绑定配置属性。
| function.json 属性 | Attribute 属性 | 说明 |
|---|---|---|
| type | 不适用 | 必须设置为 blobTrigger。 在 Azure 门户中创建触发器时,会自动设置此属性。 |
| direction | 不适用 | 必须设置为 in。 在 Azure 门户中创建触发器时,会自动设置此属性。 用法部分中已阐述异常。 |
| name | 不适用 | 表示函数代码中的 Blob 的变量的名称。 |
| 路径 | BlobPath | 要监视的容器。 可以是某种 Blob 名称模式。 |
| 连接 | Connection | 包含要用于此绑定的存储连接字符串的应用设置的名称。 如果应用设置名称以“AzureWebJobs”开始,则只能在此处指定该名称的余下部分。 例如,如果将 connection 设置为“MyStorage”,函数运行时将会查找名为“AzureWebJobsMyStorage”的应用设置。 如果将 connection 留空,函数运行时将使用名为 AzureWebJobsStorage 的应用设置中的默认存储连接字符串。连接字符串必须属于某个常规用途存储帐户,而不能属于Blob 存储帐户。如果你使用的是 版本 5. x 或更高版本,而不是连接字符串,则可以提供对定义该连接的配置节的引用。 请参阅 连接。 |
在本地进行开发时,应用设置将取 local.settings.json 文件的值。
使用情况
C#
可以将以下参数类型用于触发 blob:
StreamTextReaderstringByte[]ICloudBlob<sup>1</sup>CloudBlockBlob<sup>1</sup>CloudPageBlob<sup>1</sup>CloudAppendBlob<sup>1</sup>
<sup>1</sup> function.json 中需有 "inout" 绑定 direction 或 C# 类库中需有 FileAccess.ReadWrite。
如果尝试绑定到某个存储 SDK 类型并收到错误消息,请确保已引用正确的存储 SDK 版本。
由于整个 Blob 内容都会加载到内存中,因此,只有当 Blob 较小时才建议绑定到 string 或 Byte[]。 平时,最好使用 Stream 或 CloudBlockBlob 类型。 有关详细信息,请参阅本文后面的并发和内存使用情况。
C# 脚本
可以将以下参数类型用于触发 blob:
StreamTextReaderstringByte[]ICloudBlob<sup>1</sup>CloudBlockBlob<sup>1</sup>CloudPageBlob<sup>1</sup>CloudAppendBlob<sup>1</sup>
<sup>1</sup> function.json 中需有 "inout" 绑定 direction 或 C# 类库中需有 FileAccess.ReadWrite。
如果尝试绑定到某个存储 SDK 类型并收到错误消息,请确保已引用正确的存储 SDK 版本。
由于整个 Blob 内容都会加载到内存中,因此,只有当 Blob 较小时才建议绑定到 string 或 Byte[]。 平时,最好使用 Stream 或 CloudBlockBlob 类型。 有关详细信息,请参阅本文后面的并发和内存使用情况。
Java
@BlobTrigger 特性用于授予对触发函数的 blob 的访问权限。 有关详细信息,请参阅触发器示例。
JavaScript
使用 context.bindings.<NAME> 访问 blob 数据,其中 <NAME> 与 function.json 中定义的值匹配。
PowerShell
通过与 function.json 文件中绑定名称参数指定的名称匹配的字符串参数访问 Blob 数据。
Python
通过类型为 InputStream的参数访问 blob 数据。 有关详细信息,请参阅触发器示例。
Blob 名称模式
可以在 function.json 的 path 属性中或者在 BlobTrigger 特性构造函数中指定 Blob 名称模式。 名称模式可以是筛选器或绑定表达式。 以下部分提供了有关示例。
Tip: 容器名称不能在名称模式中包含解析程序。
获取文件名和扩展名
以下示例演示如何分别绑定到 Blob 文件名和扩展名:
"path": "input/{blobname}.{blobextension}",
如果 Blob 名为 original-Blob1.txt,则函数代码中 blobname 和 blobextension 变量的值为 original-Blob1 和 txt。
按 Blob 名称筛选
以下示例仅根据 input 容器中以字符串“original-”开头的 Blob 触发:
"path": "input/original-{name}",
如果 Blob 名称为 original-Blob1.txt,则函数代码中 name 变量的值为 Blob1.txt。
按文件类型筛选
以下示例仅根据 .png 文件触发:
"path": "samples/{name}.png",
按文件名中的大括号筛选
若要查找文件名中的大括号,请使用两个大括号将大括号转义。 以下示例筛选名称中包含大括号的 Blob:
"path": "images/{{20140101}}-{name}",
如果 Blob 名为 {20140101}-soundfile.mp3,则函数代码中的 name 变量值为 soundfile.mp3。
Metadata
C#
Blob 触发器提供了几个元数据属性。 这些属性可在其他绑定中用作绑定表达式的一部分,或者用作代码中的参数。 这些值的语义与 CloudBlob 类型相同。
| properties | 类型 | 说明 |
|---|---|---|
BlobTrigger |
string |
触发 Blob 的路径。 |
Uri |
System.Uri |
主位置的 blob 的 URI。 |
Properties |
BlobProperties | Blob 的系统属性。 |
Metadata |
IDictionary<string,string> |
Blob 的用户定义元数据。 |
例如,以下 C# 脚本和 JavaScript 示例会记录触发 blob 的路径,包括容器:
public static void Run(string myBlob, string blobTrigger, ILogger log)
{
log.LogInformation($"Full blob path: {blobTrigger}");
}
C# 脚本
Blob 触发器提供了几个元数据属性。 这些属性可在其他绑定中用作绑定表达式的一部分,或者用作代码中的参数。 这些值的语义与 CloudBlob 类型相同。
| properties | 类型 | 说明 |
|---|---|---|
BlobTrigger |
string |
触发 Blob 的路径。 |
Uri |
System.Uri |
主位置的 blob 的 URI。 |
Properties |
BlobProperties | Blob 的系统属性。 |
Metadata |
IDictionary<string,string> |
Blob 的用户定义元数据。 |
例如,以下 C# 脚本和 JavaScript 示例会记录触发 blob 的路径,包括容器:
public static void Run(string myBlob, string blobTrigger, ILogger log)
{
log.LogInformation($"Full blob path: {blobTrigger}");
}
Java
元数据在 Java 中不可用。
JavaScript
module.exports = function (context, myBlob) {
context.log("Full blob path:", context.bindingData.blobTrigger);
context.done();
};
PowerShell
可以通过 $TriggerMetadata 参数获取元数据。
Python
Python 中的元数据不可用。
Blob 回执
Azure Functions 运行时确保没有为相同的新 blob 或更新 blob 多次调用 blob 触发器函数。 为了确定是否已处理给定的 blob 版本,它会维护 blob 回执。
Azure Functions 将 Blob 回执存储在函数应用的 Azure 存储帐户中名为 azure-webjobs-hosts 的容器中(由 AzureWebJobsStorage 应用设置定义)。 Blob 回执包含以下信息:
- 触发的函数(
<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>,例如:MyFunctionApp.Functions.CopyBlob) - 容器名称
- Blob 类型(
BlockBlob或PageBlob) - Blob 名称
- ETag(blob 版本标识符,例如:
0x8D1DC6E70A277EF)
若要强制重新处理某个 blob,可从 azure-webjobs-hosts 容器中手动删除该 blob 的 blob 回执。 虽然重新处理可能不会立即发生,但它肯定会在稍后的时间点发生。 若要立即重新处理,可以更新 azure-webjobs-hosts/blobscaninfo 中的 scaninfo Blob 。 将再次扫描 LatestScan 属性后具有上次修改时间戳的任何 Blob。
有害 Blob
当给定 blob 的 blob 触发函数失败时,Azure Functions 将默认重试该函数共计 5 次。
如果 5 次尝试全部失败,Azure Functions 会将消息添加到名为 webjobs-blobtrigger-poison 的存储队列。 最大尝试次数可配置。 使用相同的 MaxDequeueCount 设置处理有害 Blob 和有害队列消息。 有害 Blob 的队列消息是包含以下属性的 JSON 对象:
- FunctionId(格式为
<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>) - BlobType(
BlockBlob或PageBlob) - ContainerName
- BlobName
- ETag(blob 版本标识符,例如:
0x8D1DC6E70A277EF)
并发和内存使用情况
Blob 触发器可在内部使用队列,因此并发函数调用的最大数量受 host.json 中的队列配置控制。 默认设置会将并发限制到 24 个调用。 此限制分别应用于使用 blob 触发器的函数。
Note: 对于使用 存储扩展插件的5.0.0 或更高版本的应用,host.js中的队列配置仅适用于队列触发器。 Blob 触发器并发由 中 host.js上的 blob 配置来控制。
消耗计划将虚拟机 (VM) 上的函数应用限制为 1.5 GB 内存。 内存由每个并发执行函数实例和函数运行时本身使用。 如果 blob 触发的函数将整个 blob 加载到内存中,该函数使用的仅用于 blob 的最大内存为 24 * 最大 blob 大小。 例如,包含 3 个由 blob 触发的函数的函数应用和默认设置,其每 VM 最大并发为 3*24 = 72 个函数调用。
JavaScript 和 Java 函数会将整个 blob 加载到内存中,并且如果绑定到 string 或 Byte[],则 C# 函数也会如此。
host.json 属性
文件 上的host.js 包含控制 blob 触发器行为的设置。 有关可用设置的详细信息,请参阅 host.json 设置部分。
后续步骤
历史资料。此文对应 2022-08-12 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 craigshoemaker)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
