处理 Azure Functions 绑定错误Handle Azure Functions binding errors

Azure Functions 中引发的错误可能来自以下任一来源:Errors raised in an Azure Functions can come from any of the following origins:

  • 使用内置 Azure Functions 触发器和绑定Use of built-in Azure Functions triggers and bindings
  • 调用底层 Azure 服务的 APICalls to APIs of underlying Azure services
  • 调用 REST 终结点Calls to REST endpoints
  • 调用客户端库、包或第三方 APICalls to client libraries, packages, or third-party APIs

遵循良好的错误处理做法对于避免数据丢失或消息遗漏非常重要。Following good error handling practices is important to avoid loss of data or missed messages. 建议的错误处理做法包括下列操作:Recommended error handling practices include the following actions:

使用结构化错误处理Use structured error handling

捕获和记录错误对于监视应用程序的运行状况至关重要。Capturing and logging errors is critical to monitoring the health of your application. 任何函数代码的最顶层应包含 try/catch 块。The top-most level of any function code should include a try/catch block. 在 catch 块中,可以捕获并记录错误。In the catch block, you can capture and log errors.

重试策略(预览版)Retry policies (preview)

可以在函数应用中的任何函数上针对任何触发器类型定义重试策略。A retry policy can be defined on any function for any trigger type in your function app. 重试策略会反复执行函数,直到成功执行了函数或达到最大重试次数。The retry policy re-executes a function until either successful execution or until the maximum number of retries occur. 可以为应用中的所有函数或单个函数定义重试策略。Retry policies can be defined for all functions in an app or for individual functions. 默认情况下,函数应用不会重试消息(除非在触发器源上设置了重试策略的特定触发器)。By default, a function app won't retry messages (aside from the specific triggers that have a retry policy on the trigger source). 每当某个执行导致未捕获的异常时,都会对重试策略进行评估。A retry policy is evaluated whenever an execution results in an uncaught exception. 最佳做法是捕获代码中的所有异常,并再次引发会导致重试的任何错误。As a best practice, you should catch all exceptions in your code and rethrow any errors that should result in a retry. 在执行的重试策略完成之前,不会写入事件中心和 Azure Cosmos DB 检查点,这意味着在完成当前批次之前,会暂停该分区上的进度。Event Hubs and Azure Cosmos DB checkpoints won't be written until the retry policy for the execution has completed, meaning progressing on that partition is paused until the current batch has completed.

重试策略选项Retry policy options

以下选项可用于定义重试策略。The following options are available for defining a retry policy.

“最大重试计数”是在最终失败之前重试执行的最大次数。Max Retry Count is the maximum number of times an execution is retried before eventual failure. 值为 -1 表示重试无限次数。A value of -1 means to retry indefinitely. 当前重试计数存储在实例的内存中。The current retry count is stored in memory of the instance. 实例可能在重试尝试之间出现故障。It's possible that an instance has a failure between retry attempts. 当实例在重试策略实施过程中发生故障时,重试计数会丢失。When an instance fails during a retry policy, the retry count is lost. 出现实例故障时,事件中心、Azure Cosmos DB 和队列存储等触发器能够恢复处理,在新实例上重试该批次,并将重试计数重置为零。When there are instance failures, triggers like Event Hubs, Azure Cosmos DB, and Queue storage are able to resume processing and retry the batch on a new instance, with the retry count reset to zero. 其他触发器(如 HTTP 和计时器)不会在新实例上恢复。Other triggers, like HTTP and timer, don't resume on a new instance. 这意味着系统只能尽力完成最大重试次数。在某些罕见情况下,执行的重试次数可能会超过最大值,而对于 HTTP 和计时器之类的触发器,重试次数可能会小于最大值。This means that the max retry count is a best effort, and in some rare cases an execution could be retried more than the maximum, or for triggers like HTTP and timer be retried less than the maximum.

“重试策略”控制重试的行为方式。Retry Strategy controls how retries behave. 下面是两个支持的重试选项:The following are two supported retry options:

选项Option 描述Description
fixedDelay 允许在指定的时间过后再进行每次重试。A specified amount of time is allowed to elapse between each retry,
exponentialBackoff 首次重试等待的时间(即延迟)最短。The first retry waits for the minimum delay. 进行后续重试时,对于每次重试,都会以指数方式向初始持续时间添加时间量,直到达到最大延迟。On subsequent retries, time is added exponentially to the initial duration for each retry, until the maximum delay is reached. 指数退避使延迟略微随机化,以便在高吞吐量方案中可以错开重试。Exponential back-off adds some small randomization to delays to stagger retries in high-throughput scenarios.

应用级配置App level configuration

可以使用 host.json 文件为应用中的所有函数定义重试策略。A retry policy can be defined for all functions in an app using the host.json file.

函数级配置Function level configuration

可以为特定函数定义重试策略。A retry policy can be defined for a specific function. 特定于函数的配置优先于应用级配置。Function-specific configuration takes priority over app-level configuration.

固定延迟重试Fixed delay retry

重试需要 NuGet 包 Microsoft.Azure.WebJobs >= 3.0.23Retries require NuGet package Microsoft.Azure.WebJobs >= 3.0.23

[FixedDelayRetry(5, "00:00:10")]
public static async Task Run([EventHubTrigger("myHub", Connection = "EventHubConnection")] EventData[] events, ILogger log)
// ...

指数退避重试Exponential backoff retry

重试需要 NuGet 包 Microsoft.Azure.WebJobs >= 3.0.23Retries require NuGet package Microsoft.Azure.WebJobs >= 3.0.23

[ExponentialBackoffRetry(5, "00:00:04", "00:15:00")]
public static async Task Run([EventHubTrigger("myHub", Connection = "EventHubConnection")] EventData[] events, ILogger log)
// ...
function.json 属性function.json property 属性Attribute Property 描述Description
strategystrategy 不适用n/a 必需。Required. 要使用的重试策略。The retry strategy to use. 有效值为 fixedDelay or exponentialBackoff进行求值的基于 SQL 语言的筛选器表达式。Valid values are fixedDelay or exponentialBackoff.
maxRetryCountmaxRetryCount 不适用n/a 必需。Required. 每个函数执行允许的最大重试次数。The maximum number of retries allowed per function execution. -1 表示无限重试。-1 means to retry indefinitely.
delayIntervaldelayInterval 不适用n/a 使用 fixedDelay 策略时会在重试之间使用的延迟。The delay that will be used between retries when using fixedDelay strategy.
minimumIntervalminimumInterval 不适用n/a 使用 exponentialBackoff 策略时的最小重试延迟。The minimum retry delay when using exponentialBackoff strategy.
maximumIntervalmaximumInterval 不适用n/a 使用 exponentialBackoff 策略时的最大重试延迟。The maximum retry delay when using exponentialBackoff strategy.

预览期间的重试限制Retry limitations during preview

  • 对于 .NET 项目,可能需要手动拉入版本不低于 3.0.23 的 Microsoft.Azure.WebJobsFor .NET projects, you may need to manually pull in a version of Microsoft.Azure.WebJobs >= 3.0.23.
  • 在消耗计划中,应用可能会在重试队列中最后的消息时纵向缩减到零。In the consumption plan, the app may be scaled down to zero while retrying the final messages in a queue.
  • 在消耗计划中,应用可能会在执行重试时纵向缩减。In the consumption plan, the app may be scaled down while performing retries. 为获得最佳结果,请选择一个小于或等于 00:01:00 的重试间隔,以及小于或等于 5 的重试次数。For best results, choose a retry interval <= 00:01:00 and <= 5 retries.

在触发器复原能力的基础上使用重试支持Using retry support on top of trigger resilience

函数应用重试策略独立于触发器提供的任何重试或复原能力。The function app retry policy is independent of any retries or resiliency that the trigger provides. 函数重试策略所作用的层次只会在触发器可复原重试所作用的层次之上。The function retry policy will only layer on top of a trigger resilient retry. 例如,如果使用 Azure 服务总线,则默认情况下队列的消息传递计数为 10。For example, if using Azure Service Bus, by default queues have a message delivery count of 10. 默认传递计数是指在尝试传递队列消息 10 次后,服务总线会将该消息视为死信。The default delivery count means after 10 attempted deliveries of a queue message, Service Bus will dead-letter the message. 你可以为包含服务总线触发器的函数定义重试策略,但重试会在服务总线传递尝试次数的基础上发挥作用。You can define a retry policy for a function that has a Service Bus trigger, but the retries will layer on top of the Service Bus delivery attempts.

例如,如果你使用的默认服务总线传递计数为 10,并定义了函数重试策略 5。For instance, if you used the default Service Bus delivery count of 10, and defined a function retry policy of 5. 消息会先取消排队,将服务总线传递计数递增到 1。The message would first dequeue, incrementing the service bus delivery account to 1. 如果每个执行都失败,则在 5 次尝试触发同一消息后,该消息会被标记为已放弃。If every execution failed, after five attempts to trigger the same message, that message would be marked as abandoned. 服务总线会立即将消息重新排队,它会触发函数并将传递计数递增到 2。Service Bus would immediately requeue the message, it would trigger the function and increment the delivery count to 2. 最后,在 50 次最终尝试(10 次服务总线传递 * 每次传递时进行的 5 次函数重试)后,消息会被放弃,并在服务总线上触发死信。Finally, after 50 eventual attempts (10 service bus deliveries * five function retries per delivery), the message would be abandoned and trigger a dead-letter on service bus.


建议不要将触发器(如服务总线队列)的传递计数设置为 1,这意味着在单次函数重试循环后,消息会被立即视为死信。It is not recommended to set the delivery count for a trigger like Service Bus Queues to 1, meaning the message would be dead-lettered immediately after a single function retry cycle. 这是因为,触发器通过重试提供复原能力,而对于函数重试策略,系统只能做到“尽量遵循”,因此可能导致重试次数少于所需的重试总次数。This is because triggers provide resiliency with retries, while the function retry policy is best effort and may result in less than the desired total number of retries.

具有额外的复原能力或重试次数的触发器Triggers with additional resiliency or retries

以下触发器支持触发器源处的重试:The following triggers support retries at the trigger source:

默认情况下,多数触发器最多重试请求五次。By default, most triggers retry requests up to five times. 第五次重试后,Azure 队列存储会将消息写入有害队列After the fifth retry, both the Azure Queue storage will write a message to a poison queue. 默认的服务总线队列和主题策略会在尝试 10 次后将消息写入死信队列The default Service Bus queue and topic policy will write a message to a dead-letter queue after 10 attempts.

有关 Functions 支持的服务返回的错误的信息,请参阅 Azure Functions 错误处理概述一文的绑定错误代码部分。For information on errors returned by services supported by Functions, see the Binding error codes section of the Azure Functions error handling overview article.