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 参考

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

某些 host.json 设置只有在本地运行时才会在 local.settings.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" ],
}

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

aggregator

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

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

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

applicationInsights

控制 Application Insights 中的采样功能

{
    "applicationInsights": {
        "sampling": {
          "isEnabled": true,
          "maxTelemetryItemsPerSecond" : 5
        }
    }
}
属性 默认 说明
isEnabled true 启用或禁用采样。
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 的所有主要版本。 但是,根据 Azure Functions 运行时的版本和使用的 Durable Functions 扩展版本,host json 配置的架构略有不同。 以下示例可与 Azure Functions 2.0 和3.0 一起使用。 在这两个示例中,如果使用 Azure Functions 1.0,则可用设置是相同的,但 host.json 的“durableTask”部分应位于 host. json 配置的根目录中,而不是作为“extension”下的字段。

{
 "extensions": {
  "durableTask": {
    "hubName": "MyTaskHub",
    "storageProvider": {
      "connectionStringName": "AzureWebJobsStorage",
      "controlQueueBatchSize": 32,
      "controlQueueBufferThreshold": 256,
      "controlQueueVisibilityTimeout": "00:05:00",
      "maxQueuePollingInterval": "00:00:30",
      "partitionCount": 4,
      "trackingStoreConnectionStringName": "TrackingStorage",
      "trackingStoreNamePrefix": "DurableTask",
      "useLegacyPartitionManagement": true,
      "workItemQueueVisibilityTimeout": "00:05:00",
    },
    "tracing": {
      "traceInputsAndOutputs": false,
      "traceReplayEvents": false,
    },
    "notifications": {
      "eventGrid": {
        "topicEndpoint": "https://topic_name.chinanorth2-1.eventgrid.chinacloudapi.cn/api/events",
        "keySettingName": "EventGridKey",
        "publishRetryCount": 3,
        "publishRetryInterval": "00:00:30",
        "publishEventTypes": [
          "Started",
          "Pending",
          "Failed",
          "Terminated"
        ]
      }
    },
    "maxConcurrentActivityFunctions": 10,
    "maxConcurrentOrchestratorFunctions": 10,
    "extendedSessionsEnabled": false,
    "extendedSessionIdleTimeoutInSeconds": 30,
    "useAppLease": true,
    "useGracefulShutdown": false,
    "maxEntityOperationBatchSize": 50
  }
 }
}

任务中心名称必须以字母开头且只能包含字母和数字。 如果未指定,则函数应用的默认任务中心名称是 DurableFunctionsHub。 有关详细信息,请参阅任务中心

属性 默认 说明
hubName DurableFunctionsHub 可以使用备用任务中心名称将多个 Durable Functions 应用程序彼此隔离,即使这些应用程序使用同一存储后端。
controlQueueBatchSize 32 要从控制队列中一次性拉取的消息数。
controlQueueBufferThreshold 适用于 Python 的消耗计划:32
适用于 JavaScript 和 C# 的消耗计划:128
专用/高级计划:256
一次可以在内存中缓冲的控制队列消息数,此时调度程序将等待,然后再将任何其他消息出队。
partitionCount 4 控制队列的分区计数。 可以是 1 到 16 之间的正整数。
controlQueueVisibilityTimeout 5 分钟 已取消排队的控制队列消息的可见性超时。
workItemQueueVisibilityTimeout 5 分钟 已取消排队的工作项队列消息的可见性超时。
maxConcurrentActivityFunctions 消耗计划:10
专用/高级计划:当前计算机上的处理器数的 10 倍
可以在单个主机实例上并发处理的活动函数的最大数目。
maxConcurrentOrchestratorFunctions 消耗计划:5
专用/高级计划:当前计算机上的处理器数的 10 倍
可以在单个主机实例上并发处理的业务流程协调程序函数的最大数目。
maxQueuePollingInterval 30 秒 最大的控制和工作项队列轮询时间间隔,采用 hh:mm:ss 格式。 值越高,可能导致的消息处理延迟也越高。 值越低,可能导致的存储成本会越高,因为存储事务数增高。
connectionStringName (2.x)
azureStorageConnectionStringName (1.x)
AzureWebJobsStorage 应用设置的名称,其中的 Azure 存储连接字符串用于管理基础的 Azure 存储资源。
trackingStoreConnectionStringName 连接字符串的名称,用于“历史记录”和“实例”表。 如果未指定,则使用 connectionStringName (Durable 2.x) 或 azureStorageConnectionStringName (Durable 1.x) 连接。
trackingStoreNamePrefix 指定 trackingStoreConnectionStringName 时用于“历史记录”和“实例”表的前缀。 如果未设置,则默认前缀值为 DurableTask。 如果 trackingStoreConnectionStringName 未指定,则“历史记录”和“实例”表会使用 hubName 值作为其前缀,trackingStoreNamePrefix 的任何设置都会被忽略。
traceInputsAndOutputs false 一个指示是否跟踪函数调用的输入和输出的值。 跟踪函数执行事件时的默认行为是在函数调用的序列化输入和输出中包括字节数。 此行为提供的有关输入和输出情况的信息是最少的,不会导致日志膨胀,也不会无意中将敏感信息公开。 将此属性设置为 true 会导致默认函数日志记录将函数输入和输出的整个内容都记录下来。
traceReplayEvents false 一个值,该值指示是否将业务流程重播事件写入到 Application Insights。
eventGridTopicEndpoint Azure 事件网格自定义主题终结点的 URL。 设置此属性后,业务流程生命周期通知事件就会发布到此终结点。 此属性支持应用设置解析。
eventGridKeySettingName 应用设置的名称,该设置包含的密钥用于在 EventGridTopicEndpoint 上通过 Azure 事件网格自定义主题进行身份验证。
eventGridPublishRetryCount 0 发布到事件网格主题失败时要重试的次数。
eventGridPublishRetryInterval 5 分钟 事件网格发布重试间隔(采用 hh:mm:ss 格式)。
eventGridPublishEventTypes 要发布到事件网格的事件类型列表。 如果未指定,则将发布所有事件类型。 允许的值包括 StartedCompletedFailedTerminated
useAppLease 如果设置为 true,应用将要求在处理任务中心消息之前获取应用级别 blob 租约。 有关详细信息,请参阅灾难恢复和地理分布文档。 从 v2.3.0 开始可用。
useLegacyPartitionManagement false 设置为 false 时,使用分区管理算法来减少横向扩展时重复执行函数的可能性。从 v2.3.0 开始可用。
useGracefulShutdown false (预览)启用正常关闭以减少主机关闭导致进程内函数执行失败的机会。
maxEntityOperationBatchSize(2.6.1) 消耗计划:50
专用/高级计划:5000
批处理形式处理的最大实体操作数。 如果设置为 1,则禁用批处理,并且每个操作消息由单独的函数调用处理。

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

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
    }
}
属性 默认 说明
enabled 指定是否已启用该功能。
healthCheckInterval 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"
}

logger

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

{
    "logger": {
        "categoryFilter": {
            "defaultLevel": "Information",
            "categoryLevels": {
                "Host": "Error",
                "Function": "Error",
                "Host.Aggregator": "Information"
            }
        }
    }
}
属性 默认 说明
categoryFilter n/a 指定按类别进行筛选
defaultLevel 信息 对于 categoryLevels 数组中未指定的任何类别,会将此级别和更高级别的日志发送到 Application Insights。
categoryLevels n/a 一个类别数组,指定每个类别的、要发送到 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 消息处理失败时的重试间隔时间。
batchSize 16 Functions 运行时同时检索并并行处理的队列消息数。 当处理的数量下降到 newBatchThreshold 时,运行时可获取另一个批,并开始处理这些消息。 因此,每个函数处理的最大并发消息数是 batchSize 加上 newBatchThreshold。 此限制分别应用于各个队列触发的函数。

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

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

SendGrid

SendGrind 输出绑定的配置设置

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

serviceBus

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

{
    "serviceBus": {
      "maxConcurrentCalls": 16,
      "prefetchCount": 100,
      "autoRenewTimeout": "00:05:00",
      "autoComplete": true
    }
}
属性 默认 说明
maxConcurrentCalls 16 消息泵应该对回调发起的最大并发调用数。 默认情况下,Functions 运行时同时处理多条消息。 若要指示运行时一次只处理单个队列或主题消息,请将 maxConcurrentCalls 设置为 1。
prefetchCount 不适用 基础 MessageReceiver 将要使用的默认 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 不适用 尝试获取锁的间隔时间。

tracing

版本 1.x

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

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

watchDirectories

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

{
    "watchDirectories": [ "Shared" ]
}

后续步骤