Azure Functions 2.x 及更高版本的 host.json 参考

Artículo
09/20/2024

host.json 元数据文件包含影响函数应用实例中所有函数的配置选项。本文列出了从 Azure Functions 运行时 2.x 版开始可用的设置。

注意

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

其他函数应用程序配置选项根据函数应用的运行位置进行管理：

部署到 Azure：在应用程序设置中
在本地计算机上：在 local.settings.json 文件中。

host.json 中与绑定相关的配置将同样地应用于函数应用中的每个函数。

还可以使用应用程序设置来按环境覆盖或应用设置。

示例 host.json 文件

以下版本 2.x+ 的示例 host.json 文件指定了所有可能的选项（不包括仅供内部使用的任何选项）。

{
    "version": "2.0",
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    },
    "concurrency": { 
            "dynamicConcurrencyEnabled": true, 
            "snapshotPersistenceEnabled": true 
        },
    "extensions": {
        "blobs": {},
        "cosmosDb": {},
        "durableTask": {},
        "eventHubs": {},
        "http": {},
        "queues": {},
        "sendGrid": {},
        "serviceBus": {}
    },
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.0.0, 5.0.0)"
    },
    "functions": [ "QueueProcessor", "GitHubWebHook" ],
    "functionTimeout": "00:05:00",
    "healthMonitor": {
        "enabled": true,
        "healthCheckInterval": "00:00:10",
        "healthCheckWindow": "00:02:00",
        "healthCheckThreshold": 6,
        "counterThreshold": 0.80
    },
    "logging": {
        "fileLoggingMode": "debugOnly",
        "logLevel": {
          "Function.MyFunction": "Information",
          "default": "None"
        },
        "applicationInsights": {
            "samplingSettings": {
              "isEnabled": true,
              "maxTelemetryItemsPerSecond" : 20,
              "evaluationInterval": "01:00:00",
              "initialSamplingPercentage": 100.0, 
              "samplingPercentageIncreaseTimeout" : "00:00:01",
              "samplingPercentageDecreaseTimeout" : "00:00:01",
              "minSamplingPercentage": 0.1,
              "maxSamplingPercentage": 100.0,
              "movingAverageRatio": 1.0,
              "excludedTypes" : "Dependency;Event",
              "includedTypes" : "PageView;Trace"
            },
            "dependencyTrackingOptions": {
                "enableSqlCommandTextInstrumentation": true
            },
            "enableLiveMetrics": true,
            "enableDependencyTracking": true,
            "enablePerformanceCountersCollection": true,            
            "httpAutoCollectionOptions": {
                "enableHttpTriggerExtendedInfoCollection": true,
                "enableW3CDistributedTracing": true,
                "enableResponseHeaderInjection": true
            },
            "snapshotConfiguration": {
                "agentEndpoint": null,
                "captureSnapshotMemoryWeight": 0.5,
                "failedRequestLimit": 3,
                "handleUntrackedExceptions": true,
                "isEnabled": true,
                "isEnabledInDeveloperMode": false,
                "isEnabledWhenProfiling": true,
                "isExceptionSnappointsEnabled": false,
                "isLowPrioritySnapshotUploader": true,
                "maximumCollectionPlanSize": 50,
                "maximumSnapshotsRequired": 3,
                "problemCounterResetInterval": "24:00:00",
                "provideAnonymousTelemetry": true,
                "reconnectInterval": "00:15:00",
                "shadowCopyFolder": null,
                "shareUploaderProcess": true,
                "snapshotInLowPriorityThread": true,
                "snapshotsPerDayLimit": 30,
                "snapshotsPerTenMinutesLimit": 1,
                "tempFolder": null,
                "thresholdForSnapshotting": 1,
                "uploaderProxy": null
            }
        }
    },
    "managedDependency": {
        "enabled": true
    },
    "singleton": {
      "lockPeriod": "00:00:15",
      "listenerLockPeriod": "00:01:00",
      "listenerLockRecoveryPollingInterval": "00:01:00",
      "lockAcquisitionTimeout": "00:01:00",
      "lockAcquisitionPollingInterval": "00:00:03"
    },
    "telemetryMode": "OpenTelemetry",
    "watchDirectories": [ "Shared", "Test" ],
    "watchFiles": [ "myFile.txt" ]
}

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

aggregator

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

{
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    }
}

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

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

applicationInsights

此设置是日志记录的子项。

Application Insights 的控制选项，包括采样选项。

若要了解完整的 JSON 结构，请参阅前面的示例 host.json 文件。

注意

日志采样可能会导致一些执行不会显示在 Application Insights 监视器边栏选项卡中。若要避免日志采样，请将 excludedTypes: "Request" 添加到 samplingSettings 值。

属性	默认	说明
samplingSettings	不适用	请参阅 applicationInsights.samplingSettings。
dependencyTrackingOptions	不适用	请参阅 applicationInsights.dependencyTrackingOptions。
enableLiveMetrics	true	启用实时指标收集。
enableDependencyTracking	true	自定义依赖项跟踪。
enablePerformanceCountersCollection	true	启用 Kudu 性能计数器收集。
liveMetricsInitializationDelay	00:00:15	仅限内部使用。
httpAutoCollectionOptions	不适用	请参阅 applicationInsights.httpAutoCollectionOptions。
snapshotConfiguration	不适用	请参阅 applicationInsights.snapshotConfiguration。

applicationInsights.samplingSettings

有关这些设置的详细信息，请参阅 Application Insights 中的采样。

属性	默认	说明
isEnabled	true	启用或禁用采样。
maxTelemetryItemsPerSecond	20	每个服务器主机上每秒记录的遥测项的目标数目。如果应用在多个主机上运行，请将此值降低至总体目标流量率的范围内。
evaluationInterval	01:00:00	会重新评估当前遥测速率的间隔。评估以移动平均线形式进行执行。可能想要缩短此间隔（如果遥测很容易就激增）。
initialSamplingPercentage	100.0	采样过程开始时应用的初始采样百分比，以动态改变百分比。不要在调试时减小值。
samplingPercentageIncreaseTimeout	00:00:01	采样百分比值更改时，此属性确定多久之后允许 Application Insights 再次提升采样百分比以捕获更多数据。
samplingPercentageDecreaseTimeout	00:00:01	采样百分比值更改时，此属性确定多久之后允许 Application Insights 再次降低采样百分比以捕获更少数据。
minSamplingPercentage	0.1	随着采样百分比变化，此属性确定允许的最小采样百分比。
maxSamplingPercentage	100.0	随着采样百分比变化，此属性确定允许的最大采样百分比。
movingAverageRatio	1.0	在移动平均线的计算中，权重分配给最新的值。使用等于或小于 1 的值。较小的值会使算法不易受突然的更改影响。
excludedTypes	null	不要采样的分号分隔类型列表。承认的类型为：`Dependency`、`Event`、`Exception`、`PageView`、`Request` 和 `Trace`。指定类型的所有实例都会传输；对未指定的类型进行采样。
includedTypes	null	要采样的分号分隔类型列表；空列表暗示所有类型。 `excludedTypes` 中列出的类型替代此处列出的类型。承认的类型为：`Dependency`、`Event`、`Exception`、`PageView`、`Request` 和 `Trace`。指定类型的实例都会采样；未指定或未暗示的类型将进行传输而不采样。

applicationInsights.httpAutoCollectionOptions

属性	默认	说明
enableHttpTriggerExtendedInfoCollection	true	启用或禁用 HTTP 触发器的扩展 HTTP 请求信息：传入请求关联标头、多检测密钥支持、HTTP 方法、路径及响应。
enableW3CDistributedTracing	true	启用或禁用对 W3C 分布式跟踪协议的支持（并开启旧版关联架构）。如果 `enableHttpTriggerExtendedInfoCollection` 为 true，则默认启用。如果 `enableHttpTriggerExtendedInfoCollection` 为 false，则此标志仅适用于传出请求，而不适用于传入请求。
enableResponseHeaderInjection	true	启用或禁用将多组件关联标头注入响应。启用注入将在使用多个检测密钥时允许 Application Insights 构造应用程序映射。如果 `enableHttpTriggerExtendedInfoCollection` 为 true，则默认启用。如果 `enableHttpTriggerExtendedInfoCollection` 为 false，则此设置不适用。

applicationInsights.dependencyTrackingOptions

属性	默认	说明
enableSqlCommandTextInstrumentation	false	启用收集 SQL 查询全文的功能，默认情况下禁用该功能。若要详细了解如何收集 SQL 查询文本，请参阅使用高级 SQL 跟踪获取完整的 SQL 查询。

applicationInsights.snapshotConfiguration

有关快照的详细信息，请参阅 .NET 应用中发生异常时调试快照和排查启用 Application Insights Snapshot Debugger 或查看快照时遇到的问题。

属性	默认	说明
agentEndpoint	null	用于连接到 Application Insights Snapshot Debugger 服务的终结点。如果为 null，则使用默认终结点。
captureSnapshotMemoryWeight	0.5	检查是否有足够内存来拍摄快照时，为当前进程内存大小指定的权重。预期值为大于 0 的正确分数 (0 < CaptureSnapshotMemoryWeight < 1)。
failedRequestLimit	3	禁用遥测处理器之前请求快照的失败请求数限制。
handleUntrackedExceptions	true	启用或禁用不由 Application Insights 遥测跟踪的异常跟踪。
isEnabled	true	启用或禁用快照收集
isEnabledInDeveloperMode	false	启用或禁用在开发人员模式下启用快照收集。
isEnabledWhenProfiling	true	启用或禁用快照创建，即使 Application Insights Profiler 正在收集详细的分析会话。
isExceptionSnappointsEnabled	false	启用或禁用异常筛选。
isLowPrioritySnapshotUploader	true	确定是否使用低于正常优先级运行 SnapshotUploader 进程。
maximumCollectionPlanSize	50	在任何时候可以跟踪的最大问题数，范围为 1 到 9999。
maximumSnapshotsRequired	3	为单个问题收集的最大快照数，范围为 1 到 999。应用程序中可将问题视为单个 throw 语句。为问题收集的快照数达到此值后，将不再为该问题收集更多的快照直到重置问题计数器（请参阅 `problemCounterResetInterval`）并再次达到 `thresholdForSnapshotting` 限制。
problemCounterResetInterval	24:00:00	重置问题计数器的频率，范围为一分钟到七天。达到此间隔时间后，所有问题计数都将重置为零。已达到拍摄快照的阈值但尚未在 `maximumSnapshotsRequired` 中生成快照数的现有问题仍处于活动状态。
provideAnonymousTelemetry	true	确定是否将匿名使用情况和错误的遥测数据发送给 Microsoft。如果与 Microsoft 联系以通过 Snapshot Debugger 帮助解决问题，则可以使用此遥测数据。它还用于监视使用模式。
reconnectInterval	00:15:00	重新连接到 Snapshot Debugger 终结点的频率。允许的范围是一分钟到一天。
shadowCopyFolder	null	指定用于影子副本二进制文件的文件夹。如未设置，则按顺序尝试下列环境变量指定的文件夹：Fabric_Folder_App_Temp、LOCALAPPDATA、APPDATA、TEMP。
shareUploaderProcess	true	如果为 true，则只有一个 SnapshotUploader 实例将为共享 InstrumentationKey 的多个应用收集和上传快照。如果设为 false，则 SnapshotUploader 对于每个 (ProcessName, InstrumentationKey) 元组都是唯一的。
snapshotInLowPriorityThread	true	确定是否在低 IO 优先级线程中处理快照。创建快照是一个快速操作，但为了将快照上传到 Snapshot Debugger 服务，必须首先将其以小型转储的形式写入磁盘。这在 SnapshotUploader 进程中发生。如果将此值设为 true，则使用低优先级 IO 来写入小型转储，这不会与应用程序争用资源。如果将此值设为 false，会加速创建小型转储，同时降低应用程序的运行速度。
snapshotsPerDayLimit	30	一天（24 小时）中允许的最大快照数。此限制还强制用于 Application Insights 服务端。上传速率限制为每个应用程序（即每个检测密钥）每天 50 个。此值有助于阻止创建在上传过程中最终会遭到拒绝的其他快照。如果此值为零则完全删除限制，不建议这样做。
snapshotsPerTenMinutesLimit	1	10 分钟内允许的最大快照数。尽管此值没有上限，但由于它可能影响应用程序性能，因此在生产工作负荷中增加它时应谨慎。创建快照会很快，但创建快照的小型转储并将其上传到 Snapshot Debugger 服务则慢得多，它将与应用程序争用资源（CPU 和 I/O）。
tempFolder	null	指定用于写入小型转储并上传日志文件的文件夹。如未设置，则使用 %TEMP%\Dumps。
thresholdForSnapshotting	1	Application Insights 请求快照之前需要查看异常的次数。
uploaderProxy	null	替代 Snapshot Uploader 进程中使用的代理服务器。如果应用程序通过代理服务器连接到 Internet，则可能需要使用此设置。 Snapshot Collector 在应用程序的进程内运行，并使用相同的代理设置。但是，Snapshot Uploader 作为单独的进程运行，并且你可能需要手动配置代理服务器。如果此值为 null，Snapshot Collector 将尝试通过检查 `System.Net.WebRequest.DefaultWebProxy` 并将值传递到 Snapshot Uploader 来自动检测代理的地址。如果此值不为 null，则不会使用自动检测，并且将在 Snapshot Uploader 中使用此处指定的代理服务器。

Blob

可在存储 Blob 触发器和绑定中查找配置设置。

控制台

此设置是日志记录的子项。它在未处于调试模式时控制控制台日志记录。

{
    "logging": {
    ...
        "console": {
          "isEnabled": false,
          "DisableColors": true
        },
    ...
    }
}

属性	默认	说明
DisableColors	false	在 Linux 上禁用容器日志的日志格式设置。如果在 Linux 上运行时希望在容器日志中看到不需要的 ANSI 控制字符，则设置为 true。
isEnabled	false	启用或禁用控制台日志记录。

Azure Cosmos DB

可在 Azure Cosmos DB 触发器和绑定中查找配置设置。

customHandler

自定义处理程序的配置设置。有关详细信息，请参阅 Azure Functions 自定义处理程序。

"customHandler": {
  "description": {
    "defaultExecutablePath": "server",
    "workingDirectory": "handler",
    "arguments": [ "--port", "%FUNCTIONS_CUSTOMHANDLER_PORT%" ]
  },
  "enableForwardingHttpRequest": false
}

属性	默认	说明
defaultExecutablePath	不适用	要作为自定义处理程序进程启动的可执行文件。在使用自定义处理程序时，它是必需设置，其值与函数应用根有关。
workingDirectory	函数应用根	要在其中启动自定义处理程序进程的工作目录。它是一个可选设置，其值与函数应用根有关。
参数	不适用	要传递给自定义处理程序进程的命令行参数的数组。
enableForwardingHttpRequest	false	如果设置，则仅包含 HTTP 触发器和 HTTP 输出的所有函数都将转发原始 HTTP 请求而不是自定义处理程序请求负载。

durableTask

可在 Durable Functions 的绑定中查找配置设置。

concurrency

为函数应用中的特定绑定启用动态并发。有关详细信息，请参阅动态并发。

    { 
        "concurrency": { 
            "dynamicConcurrencyEnabled": true, 
            "snapshotPersistenceEnabled": true 
        } 
    }

属性	默认	说明
dynamicConcurrencyEnabled	false	为此功能（默认处于关闭状态）支持的所有触发器启用动态并发行为。
snapshotPersistenceEnabled	true	获知的并发值会定期保存到存储中，因此新实例将从这些值而不是从 1 开始，并且必须重新获知并发值。

eventHub

可在事件中心触发器和绑定中查找配置设置。

扩展

返回包含所有特定于绑定的设置的对象的属性，例如 http 和 eventHub。

extensionBundle

使用扩展捆绑可将一组兼容的 Functions 绑定扩展添加到函数应用。若要了解详细信息，请参阅用于本地开发的扩展捆绑。

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

extensionBundle 中提供了以下属性：

properties	说明
id	Azure Functions 扩展捆绑的命名空间。
版本	要安装的捆绑包的版本。 Functions 运行时始终选取由版本范围或间隔定义的可允许最高版本。上述版本值允许从 3.3.0 到（但不包括）4.0.0 的所有捆绑包版本。有关详细信息，请参阅用于指定版本范围的间隔表示法。

注意

3.x 版扩展捆绑包目前不包含表存储绑定。目前，如果应用需要表存储，则需继续使用 2.x 版。

functions

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

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

functionTimeout

指示所有函数执行的超时持续时间。它采用 timespan 字符串格式。

计划类型	默认值（分钟）	最大值（分钟）
消耗	5	10
高级¹	30	-1（无限制）²
专用（应用服务）	30	-1（无限制）²

¹ 高级计划执行只能保证 60 分钟，但技术上不限时长。
² 值为 -1 表示无限制执行，但建议保留固定上限。

{
    "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 触发器和绑定中查找配置设置。

日志记录

控制函数应用（包括 Application Insights）的日志记录行为。

"logging": {
    "fileLoggingMode": "debugOnly",
    "logLevel": {
      "Function.MyFunction": "Information",
      "default": "None"
    },
    "console": {
        ...
    },
    "applicationInsights": {
        ...
    }
}

属性	默认	说明
fileLoggingMode	debugOnly	确定在 Azure 中运行时的文件日志记录行为。选项包括 `never`、`always` 和 `debugOnly`。在本地运行时不使用此设置。如果可能，在 Azure 中调试函数时应使用 Application Insights。使用 `always` 会对应用的冷启动行为和数据吞吐量产生负面影响。使用 Azure 门户进行调试时，默认 `debugOnly` 设置会生成日志文件。
logLevel	不适用	一个对象，它定义了用于筛选应用中的函数的日志类别。此设置允许你筛选特定函数的日志记录。有关详细信息，请参阅配置日志级别。
控制台	不适用	控制台日志记录设置。
applicationInsights	不适用	applicationInsights 设置。

managedDependency

托管依赖项是一项功能，目前仅支持基于 PowerShell 的函数。它使依赖项可以由服务自动管理。 enabled 属性设置为 true 时，requirements.psd1 文件会被处理。发布任何次要版本时会更新依赖项。有关详细信息，请参阅 PowerShell 文章中的托管依赖项。

{
    "managedDependency": {
        "enabled": true
    }
}

queues

可在存储队列触发器和绑定中查找设置。

SendGrid

可在 SendGrid 触发器和绑定中查找配置设置。

serviceBus

可在服务总线触发器和绑定中查找配置设置。

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	不适用	尝试获取锁的间隔时间。

telemetryMode

此功能目前以预览版提供。

用于为支持 OpenTelemetry 的一个或多个终结点启用 OpenTelemetry 输出格式的日志和跟踪输出。当此设置设为 OpenTelemetry 时，将使用 OpenTelemetry 输出。默认情况下，如果没有此设置，所有日志、跟踪和事件都会采用标准输出发送到 Application Insights。有关详细信息，请参阅将 OpenTelemetry 与 Azure Functions 配合使用。

版本

此值指示 host.json 的架构版本。面向 v2 运行时或更高版本的函数应用需要版本字符串 "version": "2.0"。 v2 和 v3 之间没有 host.json 架构更改。

watchDirectories

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

{
    "watchDirectories": [ "Shared" ]
}

watchFiles

一个或多个文件名称的数组，系统会监视这些文件，查看是否存在需要重启应用的更改。这样就可以保证，当这些文件中的代码发生更改时，函数会拾取更新。

{
    "watchFiles": [ "myFile.txt" ]
}

重写 host.json 值

某些情况下，可能希望为特定环境配置或修改 host.json 文件中的特定设置，而无需更改 host.json 文件本身。可以通过创建等效值作为应用程序设置来重写特定的 host.json 值。当运行时查找 AzureFunctionsJobHost__path__to__setting 格式的应用程序设置时，它将重写 JSON 中位于 path.to.setting 的等效 host.json 设置。当表示为应用程序设置时，用于指示 JSON 层次结构的点 (.) 将替换为双下划线 (__)。

假设当 Application insights 在本地运行时想要禁用 Application insights 采样。如果更改了本地 host.json 文件以禁用 Application Insights，则在部署过程中可能将此更改推送到生产应用。执行此操作更为安全的方法是创建应用程序设置作为 local.settings.json 文件中的 "AzureFunctionsJobHost__logging__applicationInsights__samplingSettings__isEnabled":"false"。可以在以下 local.settings.json 文件中查看此内容，但这不会发布：

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "{storage-account-connection-string}",
        "FUNCTIONS_WORKER_RUNTIME": "{language-runtime}",
        "AzureFunctionsJobHost__logging__applicationInsights__samplingSettings__isEnabled":"false"
    }
}

使用环境变量替代 host.json 设置的操作遵循 ASP.NET Core 命名约定。当元素结构包含数组时，应将数字数组索引视为此路径中的附加元素名称。有关详细信息，请参阅环境变量的命名。

后续步骤

了解如何更新 host.json 文件

查看环境变量中的全局设置

Compartir a través de