你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

Azure Functions 1.x 的 host.json 参考

host.json 元数据文件包含影响函数应用实例中所有函数的配置选项。 本文列出了可用于版本 1.x 运行时的设置。 JSON 架构位于 http://json.schemastore.org/host

注意

本文适用于 Azure Functions 1.x。 有关 Functions 2.x 及更高版本中的 host.json 参考,请参阅 Azure Functions 2.x 的 host.json 参考

其他函数应用配置选项是在你的应用设置中管理的。

local.settings.json 文件中的某些 host.json 设置仅在本地运行时才使用。

示例 host.json 文件

以下示例 host.json 文件指定了所有可能的选项。

{
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    },
    "applicationInsights": {
        "sampling": {
          "isEnabled": true,
          "maxTelemetryItemsPerSecond" : 5
        }
    },
    "documentDB": {
        "connectionMode": "Gateway",
        "protocol": "Https",
        "leaseOptions": {
            "leasePrefix": "prefix"
        }
    },
    "eventHub": {
      "maxBatchSize": 64,
      "prefetchCount": 256,
      "batchCheckpointFrequency": 1
    },
    "functions": [ "QueueProcessor", "GitHubWebHook" ],
    "functionTimeout": "00:05:00",
    "healthMonitor": {
        "enabled": true,
        "healthCheckInterval": "00:00:10",
        "healthCheckWindow": "00:02:00",
        "healthCheckThreshold": 6,
        "counterThreshold": 0.80
    },
    "http": {
        "routePrefix": "api",
        "maxOutstandingRequests": 20,
        "maxConcurrentRequests": 10,
        "dynamicThrottlesEnabled": false
    },
    "id": "9f4ea53c5136457d883d685e57164f08",
    "logger": {
        "categoryFilter": {
            "defaultLevel": "Information",
            "categoryLevels": {
                "Host": "Error",
                "Function": "Error",
                "Host.Aggregator": "Information"
            }
        }
    },
    "queues": {
      "maxPollingInterval": 2000,
      "visibilityTimeout" : "00:00:30",
      "batchSize": 16,
      "maxDequeueCount": 5,
      "newBatchThreshold": 8
    },
    "sendGrid": {
        "from": "Contoso Group <admin@contoso.com>"
    },
    "serviceBus": {
      "maxConcurrentCalls": 16,
      "prefetchCount": 100,
      "autoRenewTimeout": "00:05:00",
      "autoComplete": true
    },
    "singleton": {
      "lockPeriod": "00:00:15",
      "listenerLockPeriod": "00:01:00",
      "listenerLockRecoveryPollingInterval": "00:01:00",
      "lockAcquisitionTimeout": "00:01:00",
      "lockAcquisitionPollingInterval": "00:00:03"
    },
    "tracing": {
      "consoleLevel": "verbose",
      "fileLoggingMode": "debugOnly"
    },
    "watchDirectories": [ "Shared" ],
}

本文的以下各部分解释了每个顶级属性。 除非另有说明,否则其中的所有属性都是可选的。

聚合器

指定在计算 Application Insights 的指标时要聚合多少个函数调用。

{
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    }
}
属性 默认 说明
批处理大小 1000 要聚合的最大请求数。
flushTimeout 00:00:30 要聚合的最大时间段。

达到两个限制中的第一个限制时,会聚合函数调用。

applicationInsights

控制 Application Insights 中的采样功能

{
    "applicationInsights": {
        "sampling": {
          "isEnabled": true,
          "maxTelemetryItemsPerSecond" : 5
        }
    }
}
属性 默认 说明
isEnabled 启用或禁用采样。
maxTelemetryItemsPerSecond 5 开始采样所要达到的阈值。

DocumentDB

Azure Cosmos DB 触发器和绑定的配置设置。

{
    "documentDB": {
        "connectionMode": "Gateway",
        "protocol": "Https",
        "leaseOptions": {
            "leasePrefix": "prefix1"
        }
    }
}
属性 默认 说明
GatewayMode 网关 连接到 Azure Cosmos DB 服务时该函数使用的连接模式。 选项为 DirectGateway
协议 Https 连接到 Azure Cosmos DB 服务时该函数使用的连接协议。 参阅此处,了解两种模式的说明
leasePrefix 不适用 应用中所有函数要使用的租用前缀。

durableTask

Durable Functions 的配置设置。

注意

Azure Functions 运行时的所有版本均支持 Durable Functions 的所有主要版本。 但是, host.json 配置的架构因 Azure Functions 运行时的版本和所使用的 Durable Functions 扩展版本而略有不同。

以下代码提供了 durableTask中的两个设置示例:一个用于 Durable Functions 2.x,一个用于 Durable Functions 1.x。 可以将这两个示例与 Azure Functions 2.0 和 3.0 配合使用。 使用 Azure Functions 1.0 时,可用的设置不变,但 host.json 部分位于 host.json 配置的根目录,而不是位于 extensions 下的字段。

{
 "extensions": {
  "durableTask": {
    "hubName": "MyTaskHub",
    "defaultVersion": "1.0",
    "versionMatchStrategy": "CurrentOrOlder",
    "versionFailureStrategy": "Reject",
    "storageProvider": {
      "connectionStringName": "AzureWebJobsStorage",
      "controlQueueBatchSize": 32,
      "controlQueueBufferThreshold": 256,
      "controlQueueVisibilityTimeout": "00:05:00",
      "FetchLargeMessagesAutomatically": true,
      "maxQueuePollingInterval": "00:00:30",
      "partitionCount": 4,
      "trackingStoreConnectionStringName": "TrackingStorage",
      "trackingStoreNamePrefix": "DurableTask",
      "useLegacyPartitionManagement": false,
      "useTablePartitionManagement": true,
      "workItemQueueVisibilityTimeout": "00:05:00",
      "QueueClientMessageEncoding": "UTF8"
    },
    "tracing": {
      "traceInputsAndOutputs": false,
      "traceReplayEvents": false,
    },
    "notifications": {
      "eventGrid": {
        "topicEndpoint": "https://topic_name.westus2-1.eventgrid.azure.net/api/events",
        "keySettingName": "EventGridKey",
        "publishRetryCount": 3,
        "publishRetryInterval": "00:00:30",
        "publishEventTypes": [
          "Started",
          "Completed",
          "Failed",
          "Terminated"
        ]
      }
    },
    "maxConcurrentActivityFunctions": 10,
    "maxConcurrentOrchestratorFunctions": 10,
    "maxConcurrentEntityFunctions": 10,
    "extendedSessionsEnabled": false,
    "extendedSessionIdleTimeoutInSeconds": 30,
    "useAppLease": true,
    "useGracefulShutdown": false,
    "maxEntityOperationBatchSize": 50,
    "maxOrchestrationActions": 100000,
    "storeInputsInOrchestrationHistory": false
  }
 }
}
属性 默认值 说明
集线器名称 TestHubName (v1.x 中的 DurableFunctionsHub) 存储函数应用的当前状态的中心的名称。 任务中心名称必须以字母开头且只能包含字母和数字。 如果未指定名称,则使用默认值。 备用任务中心名称可用于将多个 Durable Functions 应用程序彼此隔离,即使它们使用相同的存储后端也是如此。 有关详细信息,请参阅任务中心
defaultVersion 要分配给新协调实例的默认版本。 指定版本时,新的编排实例将永久与该版本值相关联。 业务流程版本控制功能使用此设置来实现零停机部署之类的具有中断性变更的方案。 可以将任何字符串值用于版本。
版本匹配策略 当前或更早版本 一个值,该值指定在加载编排器函数时如何匹配编排版本。 有效值为:NoneStrictCurrentOrOlder。 有关详细说明,请参阅 编排版本控制
versionFailureStrategy 拒绝 指定当业务流程版本与当前 defaultVersion 值不匹配时会发生的情况的值。 有效值为 RejectFail。 有关详细说明,请参阅 编排版本管理
controlQueueBatchSize 32 要从控制队列中一次性拉取的消息数。
controlQueueBufferThreshold 适用于 Python 的消耗计划:32
其他语言的消耗计划:128
专用或高级计划:256
在内存中一次可缓冲的控制队列消息数。 达到指定数字后,调度程序会等待,直到将任何其他消息出列。 在某些情况下,减少此值可以显著减少内存消耗。
partitionCount 4 控制队列的分区计数。 此值必须是介于 1 和 16 之间的正整数。 更改此值需要配置新的任务中心。
controlQueueVisibilityTimeout 00:05:00 已出列的控制队列消息的可见性超时时间,格式为 hh:mm:ss
workItemQueueVisibilityTimeout 00:05:00 已出列的工作项队列消息的可见性超时时间,格式为 hh:mm:ss
自动获取大型消息 (FetchLargeMessagesAutomatically) 一个值,用于指定是否在编排状态查询中检索大消息。 如果设置是 true,将检索超出队列大小限制的大型消息。 当此设置为 false 时,将检索每个大型消息所对应的 blob URL。
maxConcurrentActivityFunctions 消耗计划:10
专用或高级计划:当前计算机上的处理器数 10 倍
可以在单个主机实例上并发处理的活动函数的最大数目。
maxConcurrentOrchestratorFunctions 消耗计划:5
专用或高级计划:当前计算机上的处理器数 10 倍
可以在单个主机实例上并发处理的业务流程协调程序函数的最大数目。
maxConcurrentEntityFunctions 消耗计划:5
专用或高级计划:当前计算机上的处理器数 10 倍
可在单个主机实例上并发处理的实体函数的最大数目。 仅当使用 持久任务计划程序时,此设置才适用。 否则,并发实体执行数量上限设定为 maxConcurrentOrchestratorFunctions 值。
maxQueuePollingInterval 00:00:30 最大的控制和工作项队列轮询时间间隔,格式为 hh:mm:ss。 值越高,可能导致的消息处理延迟也越高。 值越低,可能导致的存储成本会越高,因为存储事务数增高。
maxOrchestrationActions 100,000 协调器函数在单个执行周期内可执行的最大操作数。
connectionName (v2.7.0 及更高版本)
connectionStringName (v2.x)
azureStorageConnectionStringName (v1.x)
AzureWebJobsStorage 应用设置或设置集合的名称,用于指定如何连接到基础 Azure 存储资源。 提供单个应用设置时,它应该是一个 Azure 存储连接字符串。
trackingStoreConnectionName (v2.7.0 及更高版本)
trackingStoreConnectionStringName
应用设置或设置集合的名称,该集合指定如何连接到历史记录和实例表,这些表存储有关业务流程实例的执行历史记录和元数据。 提供单个应用设置时,它应该是一个 Azure 存储连接字符串。 如果未指定设置,将使用 connectionStringName 值 (v2.x) 或 azureStorageConnectionStringName 值 (v1.x) 连接。
trackingStoreNamePrefix 指定 trackingStoreConnectionStringName 时用于“历史记录”和“实例”表的前缀。 如果未指定前缀,则使用默认值 DurableTask 。 如果 trackingStoreConnectionStringName 未指定,则 History 和 Instances 表使用该值 hubName 作为其前缀,trackingStoreNamePrefix 的设置将被忽略。
跟踪输入和输出 false 一个值,该值指示是否跟踪函数调用的输入和输出。 跟踪函数执行事件时,默认行为是包含函数调用的序列化输入和输出中的字节数。 此行为提供有关输入和输出的最小信息,以便不会膨胀日志或无意中公开敏感信息。 当此属性为 true此属性时,将记录函数输入和输出的全部内容。
traceReplayEvents false 指示是否将业务流程重播事件写入到 Application Insights 的值。
logReplayEvents false 一个值,该值指示是否在应用程序日志中记录重播的执行。
eventGridTopicEndpoint Azure 事件网格自定义主题终结点的 URL。 设置此属性时,业务流程生命周期通知事件将发布到此终结点。 此属性支持应用程序设置的解决。
eventGridKeySettingName (事件网格密钥设置名称) 应用设置的名称,其中包含用于在 URL 中使用事件网格自定义主题进行身份验证的 EventGridTopicEndpoint 密钥。
eventGridPublishRetryCount 0 发布到事件网格主题失败时要重试的次数。
eventGridPublishRetryInterval 00:05:00 事件网格发布重试间隔采用 hh:mm:ss 格式。
eventGridPublishEventTypes 要发布到事件网格的事件类型列表。 如果未指定任何类型,则发布所有事件类型。 允许的值包括StartedCompletedFailedTerminated
extendedSessionsEnabled false 一个值,指定是否缓存会话编排器和实体函数会话。
extendedSessionIdleTimeoutInSeconds 30 空闲的业务流程协调程序或实体函数在卸载之前保留在内存中的秒数。 此设置仅在 extendedSessionsEnabled 设置为 true 时才使用。
useAppLease 指示应用在处理任务中心消息之前是否必须获取应用级 blob 租约的值。 有关详细信息,请参阅 Durable Functions 中的灾难恢复和异地分发。 此设置从 v2.3.0 开始可用。
useLegacyPartitionManagement false 一个值,指定要使用的分区管理算法的类型。 如果设置为 false此设置,则使用一种算法,可减少横向扩展时重复函数执行的可能性。此设置从 v2.3.0 开始可用。 不建议将此值设置为true
useTablePartitionManagement 在 v3.x 中:true
在 v2.x 中: false
一个值,指定要使用的分区管理算法的类型。 如果设置是 true,则使用一种旨在降低成本的算法,用于降低 Azure 存储 v2 帐户的成本。 此设置从 WebJobs.Extensions.DurableTask v2.10.0 开始可用。 将此设置与托管标识配合使用需要安装 WebJobs.Extensions.DurableTask v3.x 或更高版本,或者 Worker.Extensions.DurableTask v1.2.x 或更高版本。
useGracefulShutdown false (预览版)一个值,指示是否正常关闭,以减少由于主机关闭而导致进程内函数执行失败的可能性。
maxEntityOperationBatchSize 消耗计划:50
专用或高级计划:5,000
批处理形式处理的最大实体操作数。 如果此值为 1,则会禁用批处理,并且每个操作消息将由单独的函数调用处理。 此设置从 v2.6.1 开始可用。
storeInputsInOrchestrationHistory false 一个值,指定如何存储输入。 如果设置是 true,Durable Task Framework 会在 History 表中保存活动输入,并且活动函数输入显示在业务流程历史记录查询结果中。
最大Grpc消息大小(字节) 4,194,304 一个整数值,该值设置泛型远程过程调用(gRPC)客户端可以接收的消息的最大大小(以字节为单位)。 实现 DurableTaskClient 使用 gRPC 客户端来管理编排实例。 此设置适用于 Durable Functions .NET "隔离工作程序" 和 Java 应用。
grpcHttpClientTimeout 00:01:40 在 Durable Functions 中,gRPC 客户端所使用的 HTTP 客户端的超时时间,格式为 hh:mm:ss。 客户端当前支持 .NET 独立辅助角色应用 (.NET 6 及更高版本) 和 Java 应用。
队列客户端消息编码 UTF8 Azure 队列存储消息的编码策略。 有效策略是 Unicode 转换格式 -8 位 (UTF8) 和 Base64。 使用 Microsoft.Azure.WebJobs.Extensions.DurableTask 3.4.0 或更高版本或 Microsoft.Azure.Functions.Worker.Extensions.DurableTask 1.7.0 或更高版本时,此设置适用。

许多此类设置用于优化性能。 有关详细信息,请参阅性能和缩放

eventHub

事件中心触发器和绑定的配置设置。

functions

作业主机运行的函数列表。 空数组表示运行所有函数。 仅供在本地运行时使用。 在 Azure 的函数应用中,应改为按照如何在 Azure Functions 中禁用函数中的步骤禁用特定函数,而不是使用此设置。

{
    "functions": [ "QueueProcessor", "GitHubWebHook" ]
}

functionTimeout

指示所有函数的超时持续时间。 在无服务器消耗计划中,有效范围为 1 秒至 10 分钟,默认值为 5 分钟。 在应用服务计划中,没有总体限制,默认值为 null,表示没有超时。

{
    "functionTimeout": "00:05:00"
}

healthMonitor

主机运行状况监视器的配置设置。

{
    "healthMonitor": {
        "enabled": true,
        "healthCheckInterval": "00:00:10",
        "healthCheckWindow": "00:02:00",
        "healthCheckThreshold": 6,
        "counterThreshold": 0.80
    }
}
属性 默认 说明
已启用 指定是否已启用该功能。
健康检查间隔时间 10 秒 定期后台运行状况检查之间的时间间隔。
healthCheckWindow 2 分钟 healthCheckThreshold 设置结合使用的滑动时间窗口。
healthCheckThreshold 6 在启动主机回收之前,运行状况检查可以失败的最大次数。
counterThreshold 0.80 性能计数器将被视为不正常的阈值。

http

http 触发器和绑定的配置设置。

{
    "http": {
        "routePrefix": "api",
        "maxOutstandingRequests": 200,
        "maxConcurrentRequests": 100,
        "dynamicThrottlesEnabled": true
    }
}
属性 默认 说明
dynamicThrottlesEnabled false 启用后,此设置会导致请求处理管道定期检查系统性能计数器,例如连接/线程/进程/内存/cpu/等。 如果这些计数器中的任何一个超过内置高阈值 (80%),请求将被拒绝并返回 429“太忙”响应,直到计数器恢复到正常水平。
maxConcurrentRequests 无限制 (-1) 将并行执行的 HTTP 函数的最大数目。 这样,可以控制并发性,从而帮助管理资源利用率。 例如,你可能有一个使用大量系统资源(内存/CPU/套接字)的 HTTP 函数,它在并发度太高时会导致问题。 或者,某个函数向第三方服务发出出站请求,则可能需要限制这些调用的速率。 在这种情况下,应用限制可能有帮助。
maxOutstandingRequests 无限制 (-1) 在任意给定时间搁置的未完成请求数上限。 此限制包括已排队但尚未开始执行的请求以及任何正在进行的执行。 超出此限制的任何传入请求将被拒绝,并返回 429“太忙”响应。 允许调用方使用基于时间的重试策略,还可帮助控制最大请求延迟。 此设置仅控制脚本宿主执行路径中发生的排队。 其他队列(例如 ASP.NET 请求队列)仍有效,不受此设置的影响。
routePrefix api 应用到所有路由的路由前缀。 使用空字符串可删除默认前缀。

id

作业宿主的唯一 ID。 可以是不带短划线的小写 GUID。 在本地运行时必须指定。 在 Azure 中运行时,我们建议你不要设置 ID 值。 当省略 id 时,会自动在 Azure 中生成 ID。

如果跨多个函数应用共享存储帐户,请确保每个函数应用都有不同的 id。 可以省略 id 属性或手动将每个函数应用的 id 设置为不同的值。 计时器触发器使用存储锁来确保当函数应用横向扩展到多个实例时将只有一个计时器实例。 如果两个函数应用共享相同的 id 且每个都使用计时器触发器,则只会运行一个计时器。

{
    "id": "9f4ea53c5136457d883d685e57164f08"
}

记录器

控制由 ILogger 对象或 context.log 写入的日志的筛选。

{
    "logger": {
        "categoryFilter": {
            "defaultLevel": "Information",
            "categoryLevels": {
                "Host": "Error",
                "Function": "Error",
                "Host.Aggregator": "Information"
            }
        }
    }
}
属性 默认 说明
categoryFilter 不适用 指定按类别进行筛选
默认级别 信息 对于 categoryLevels 数组中未指定的任何类别,会将此级别和更高级别的日志发送到 Application Insights。
categoryLevels 不适用 一个类别数组,指定每个类别的、要发送到 Application Insights 的最低日志级别。 此处指定的类别控制以相同值开头的所有类别,较长的值优先。 在前面的示例 host.json 文件中,将在 Information 级别记录以“Host.Aggregator”开头的所有类别的日志。 在 Error 级别记录以“Host”开头的其他所有类别(例如“Host.Executor”)的日志。

queues

存储队列触发器和绑定的配置设置。

{
    "queues": {
      "maxPollingInterval": 2000,
      "visibilityTimeout" : "00:00:30",
      "batchSize": 16,
      "maxDequeueCount": 5,
      "newBatchThreshold": 8
    }
}
属性 默认 说明
maxPollingInterval(最大轮询间隔) 60000 队列轮询的最大间隔时间,以毫秒为单位。
visibilityTimeout 0 消息处理失败时的重试间隔时间。
批处理大小 16 Functions 运行时同时检索并并行处理的队列消息数。 当处理的数量下降到 newBatchThreshold 时,运行时可获取另一个批,并开始处理这些消息。 因此,每个函数处理的最大并发消息数是 batchSize 加上 newBatchThreshold。 此限制分别应用于各个队列触发的函数。

如果要避免对队列上收到的消息并行执行,可以将 batchSize 设置为 1。 但是,只有在函数于单个虚拟机 (VM) 上运行时,此设置才可消除并发。 如果函数应用横向扩展到多个 VM,每个 VM 可运行每个队列触发的函数的一个实例。

batchSize 的最大值为 32。
maxDequeueCount 5 在将某个消息移到有害队列之前,尝试处理该消息的次数。
newBatchThreshold 批处理大小/2 只要同时处理的消息数下降到此数值,运行时即检索另一个批次。

SendGrid

SendGrind 输出绑定的配置设置

{
    "sendGrid": {
        "from": "Contoso Group <admin@contoso.com>"
    }
}    
属性 默认 说明
不适用 所有函数的发件人电子邮件地址。

serviceBus

服务总线触发器和绑定的配置设置。

{ 
    "serviceBus": {
      "maxConcurrentCalls": 16,
      "prefetchCount": 100,
      "autoRenewTimeout": "00:05:00",
      "autoComplete": true
    }
}
属性 默认 说明
maxConcurrentCalls 16 消息泵应该对回调发起的最大并发调用数。 默认情况下,Functions 运行时同时处理多条消息。 若要指示运行时一次只处理单个队列或主题消息,请将 maxConcurrentCalls 设置为 1。
prefetchCount 不适用 基础 ServiceBusReceiver 将要使用的默认 PrefetchCount。
autoRenewTimeout 00:05:00 自动续订消息锁的最长持续时间。
autoComplete 如果为 true,则触发器会在成功执行操作后自动完成消息处理。 如果为 false,则函数负责在返回之前完成消息。

singleton

单一实例锁行为的配置设置。 有关详细信息,请参阅有关单一实例支持的 GitHub 问题

{
    "singleton": {
      "lockPeriod": "00:00:15",
      "listenerLockPeriod": "00:01:00",
      "listenerLockRecoveryPollingInterval": "00:01:00",
      "lockAcquisitionTimeout": "00:01:00",
      "lockAcquisitionPollingInterval": "00:00:03"
    }
}
属性 默认 说明
lockPeriod 00:00:15 占用函数级锁的时间段。 锁自动续订。
listenerLockPeriod 00:01:00 占用侦听器锁的时间段。
listenerLockRecoveryPollingInterval 00:01:00 在启动时无法获取侦听器锁的情况下,用于恢复侦听器锁的时间间隔。
lockAcquisitionTimeout 00:01:00 运行时尝试获取锁的最长时间。
lockAcquisitionPollingInterval 不适用 尝试获取锁的间隔时间。

跟踪

版本 1.x

使用 TraceWriter 对象创建的日志的配置设置。 若要了解详细信息,请参阅 [C# 日志记录]。

{
    "tracing": {
      "consoleLevel": "verbose",
      "fileLoggingMode": "debugOnly"
    }
}
属性 默认 说明
consoleLevel info 控制台日志记录的跟踪级别。 选项包括:offerrorwarninginfoverbose
fileLoggingMode debugOnly 文件日志记录的跟踪级别。 选项包括 neveralwaysdebugOnly

watchDirectories

应该监视其更改情况的一组共享代码目录。 确保当这些目录中的代码发生更改时,函数会拾取这些更改。

{
    "watchDirectories": [ "Shared" ]
}

后续步骤