適用於 Azure Functions 2.x 的 host.json 參考host.json reference for Azure Functions 2.x

host.json 中繼資料檔案所包含的全域設定選項會影響函式應用程式的所有函式。The host.json metadata file contains global configuration options that affect all functions for a function app. 本文列出 v2 執行階段可用的設定。This article lists the settings that are available for the v2 runtime.

注意

本文適用於 Azure Functions 2.x。This article is for Azure Functions 2.x. 有關 Functions 1.x 中 host.json 的參考,請參閱適用於 Azure Functions 1.x 的 host.json 參考For a reference of host.json in Functions 1.x, see host.json reference for Azure Functions 1.x.

其他函數應用程式設定選項的管理是在應用程式設定中進行。Other function app configuration options are managed in your app settings.

有些 host.json 設定只有在本機執行時,才會在 local.settings.json 檔案中使用。Some host.json settings are only used when running locally in the local.settings.json file.

範例 host.json 檔案Sample host.json file

下列範例 host.json 檔案已指定所有可能的選項。The following sample host.json files have all possible options specified.

{
    "version": "2.0",
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    },
    "extensions": {
        "cosmosDb": {},
        "durableTask": {},
        "eventHubs": {},
        "http": {},
        "queues": {},
        "sendGrid": {},
        "serviceBus": {}
    },
    "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" : 5
            }
        }
    },
    "singleton": {
      "lockPeriod": "00:00:15",
      "listenerLockPeriod": "00:01:00",
      "listenerLockRecoveryPollingInterval": "00:01:00",
      "lockAcquisitionTimeout": "00:01:00",
      "lockAcquisitionPollingInterval": "00:00:03"
    },
    "watchDirectories": [ "Shared", "Test" ],
    "managedDependency": {
        "enabled": true
    }
}

本文的下列各節說明每個最上層屬性。The following sections of this article explain each top-level property. 除非另有說明,否則全部都是選擇項目。All are optional unless otherwise indicated.

aggregatoraggregator

指定計算 Application Insights 的計量時彙總多少函式引動過程。Specifies how many function invocations are aggregated when calculating metrics for Application Insights.

{
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    }
}
屬性Property 預設Default 描述Description
batchSizebatchSize 10001000 要彙總的要求數目上限。Maximum number of requests to aggregate.
flushTimeoutflushTimeout 00:00:3000:00:30 要彙總的最長期間。Maximum time period to aggregate.

達到兩個限制的第一個限制時,會彙總函式引動過程。Function invocations are aggregated when the first of the two limits are reached.

applicationInsightsapplicationInsights

此設定是 logging 的子系。This setting is a child of logging.

控制 Application Insights 中的取樣功能Controls the sampling feature in Application Insights.

{
    "applicationInsights": {
        "samplingSettings": {
          "isEnabled": true,
          "maxTelemetryItemsPerSecond" : 5
        }
    }
}

注意

記錄取樣可能會造成一些執行不會顯示在 Application Insights 監視器刀鋒視窗。Log sampling may cause some executions to not show up in the Application Insights monitor blade.

內容Property 預設Default 描述Description
isEnabledisEnabled true 啟用或停用取樣。Enables or disables sampling.
maxTelemetryItemsPerSecondmaxTelemetryItemsPerSecond 55 取樣的開始臨界值。The threshold at which sampling begins.

cosmosDbcosmosDb

可在 Cosmos DB 觸發程序和繫結中找到組態設定。Configuration setting can be found in Cosmos DB triggers and bindings.

durableTaskdurableTask

可在 Durable Functions 的繫結中找到組態設定。Configuration setting can be found in bindings for Durable Functions.

eventHubeventHub

可在事件中樞觸發程序和繫結中找到組態設定。Configuration settings can be found in Event Hub triggers and bindings.

擴充功能extensions

傳回包含所有繫結特定設定 (例如 httpeventHub) 之物件的屬性。Property that returns an object that contains all of the binding-specific settings, such as http and eventHub.

函數functions

工作主機所執行的函式清單。A list of functions that the job host runs. 空陣列表示已執行所有函式。An empty array means run all functions. 預定只能在本機執行時使用。Intended for use only when running locally. 在 Azure 的函數應用程式中,您應該改為依照如何停用 Azure Functions 中的函式中的步驟來停用特定函式,而不是使用此設定。In function apps in Azure, you should instead follow the steps in How to disable functions in Azure Functions to disable specific functions rather than using this setting.

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

functionTimeoutfunctionTimeout

指出所有函式的逾時持續期間。Indicates the timeout duration for all functions. 它會遵循 timespan 字串格式。It follows the timespan string format. 在無伺服器的使用情況方案中,有效範圍是從 1 秒到 10 分鐘,而預設值是 5 分鐘。In a serverless Consumption plan, the valid range is from 1 second to 10 minutes, and the default value is 5 minutes.
在專用 (App Service) 方案中, 沒有整體限制, 而且預設值取決於執行階段版本:In a Dedicated (App Service) plan, there is no overall limit, and the default depends on the runtime version:

  • 1.x 版: 預設值為null, 表示沒有超時。Version 1.x: the default is null, which indicates no timeout.
  • 2.x 版: 預設值為30分鐘。Version 2.x: the default value is 30 minutes. 的值表示-1未系結的執行。A value of -1 indicates unbounded execution.
{
    "functionTimeout": "00:05:00"
}

healthMonitorhealthMonitor

主機健康情況監視器的組態設定。Configuration settings for Host health monitor.

{
    "healthMonitor": {
        "enabled": true,
        "healthCheckInterval": "00:00:10",
        "healthCheckWindow": "00:02:00",
        "healthCheckThreshold": 6,
        "counterThreshold": 0.80
    }
}
屬性Property 預設Default 描述Description
enabledenabled true 指定是否已啟用此功能。Specifies whether the feature is enabled.
healthCheckIntervalhealthCheckInterval 10 秒10 seconds 定期背景健康情況檢查之間的時間間隔。The time interval between the periodic background health checks.
healthCheckWindowhealthCheckWindow 2 分鐘2 minutes healthCheckThreshold 設定搭配使用的滑動時間範圍。A sliding time window used in conjunction with the healthCheckThreshold setting.
healthCheckThresholdhealthCheckThreshold 66 在主機回收起始之前,健康情況檢查可以失敗的最大次數。Maximum number of times the health check can fail before a host recycle is initiated.
counterThresholdcounterThreshold 0.800.80 系統會將效能計數器視為狀況不良的閾值。The threshold at which a performance counter will be considered unhealthy.

httphttp

可在 HTTP 觸發程序和繫結中找到組態設定。Configuration settings can be found in http triggers and bindings.

{
    "http": {
        "routePrefix": "api",
        "maxOutstandingRequests": 200,
        "maxConcurrentRequests": 100,
        "dynamicThrottlesEnabled": true
    }
}
屬性Property 預設Default 描述Description
routePrefixroutePrefix apiapi 適用於所有路由的路由前置詞。The route prefix that applies to all routes. 若要移除預設前置詞,請使用空字串。Use an empty string to remove the default prefix.
maxOutstandingRequestsmaxOutstandingRequests 200*200* 在任何指定時間保留的未完成要求數目上限。The maximum number of outstanding requests that are held at any given time. 此限制包括已排入佇列但尚未開始執行的要求,以及任何進行中的執行。This limit includes requests that are queued but have not started executing, as well as any in progress executions. 會以 429「忙碌」回應來拒絕任何超過此限制的連入要求。Any incoming requests over this limit are rejected with a 429 "Too Busy" response. 這樣可讓呼叫者採用以時間為基礎的重試策略,並且也協助您控制要求延遲的上限。That allows callers to employ time-based retry strategies, and also helps you to control maximum request latencies. 此動作只會控制在指令碼主機執行路徑內發生的佇列處理。This only controls queuing that occurs within the script host execution path. 其他佇列 (例如 ASP.NET 要求佇列) 仍然有效,且不受此設定的影響。Other queues such as the ASP.NET request queue will still be in effect and unaffected by this setting. *預設版本 1.x 未繫結 (-1)。*The default for version 1.x is unbounded (-1). 在取用方案中,版本 2.x 的預設值是 200。The default for version 2.x in a consumption plan is 200. 預設版本 2.x 專用的方案中未繫結 (-1)。The default for version 2.x in a dedicated plan is unbounded (-1).
maxConcurrentRequestsmaxConcurrentRequests 100*100* 要平行執行的 HTTP 函式數目上限。The maximum number of http functions that will be executed in parallel. 這可讓您控制並行作業,幫助您管理資源使用率。This allows you to control concurrency, which can help manage resource utilization. 例如,您可能會有使用大量系統資源 (記憶體/CPU/通訊端) 的 HTTP 函式,以致於並行率太高時會造成問題。For example, you might have an http function that uses a lot of system resources (memory/cpu/sockets) such that it causes issues when concurrency is too high. 或者,如果函式對第三方服務發出傳出要求,則需要限制這些呼叫的速率。Or you might have a function that makes outbound requests to a third party service, and those calls need to be rate limited. 在這些情況下,套用節流會有所幫助。In these cases, applying a throttle here can help. *預設版本 1.x 未繫結 (-1)。*The default for version 1.x is unbounded (-1). 在取用方案中,版本 2.x 的預設值是 100。The default for version 2.x in a consumption plan is 100. 預設版本 2.x 專用的方案中未繫結 (-1)。The default for version 2.x in a dedicated plan is unbounded (-1).
dynamicThrottlesEnableddynamicThrottlesEnabled true*true* 啟用時,此設定會促使要求處理管線定期檢查系統效能計數器,例如連線/執行緒/處理程序/記憶體/CPU/其他,而且如果這些計數器中任一個超過內建的臨界值上限 (80%),則要求會遭到拒絕,並包含 429「忙碌」的回應,直到計數器回到正常水平。When enabled, this setting causes the request processing pipeline to periodically check system performance counters like connections/threads/processes/memory/cpu/etc. and if any of those counters are over a built-in high threshold (80%), requests will be rejected with a 429 "Too Busy" response until the counter(s) return to normal levels. *預設版本 1.x 為 false。*The default for version 1.x is false. 在取用方案中,版本 2.x 的預設值是 true。The default for version 2.x in a consumption plan is true. 在專屬方案中,版本 2.x 的預設值是 false。The default for version 2.x in a dedicated plan is false.

logginglogging

控制函數應用程式 (包括 Application Insights) 的記錄行為。Controls the logging behaviors of the function app, including Application Insights.

"logging": {
    "fileLoggingMode": "debugOnly",
    "logLevel": {
      "Function.MyFunction": "Information",
      "default": "None"
    },
    "console": {
        ...
    },
    "applicationInsights": {
        ...
    }
}
屬性Property 預設Default 描述Description
fileLoggingModefileLoggingMode debugOnlydebugOnly 定義已啟用何種檔案記錄層級。Defines what level of file logging is enabled. 選項為 neveralwaysdebugOnlyOptions are never, always, debugOnly.
logLevellogLevel n/an/a 為應用程式中的函式定義記錄類別篩選的物件。Object that defines the log category filtering for functions in the app. 2.x 版會依循 ASP.NET Core 的記錄類別篩選配置。Version 2.x follows the ASP.NET Core layout for log category filtering. 這可讓您篩選特定函式的記錄。This lets you filter logging for specific functions. 如需詳細資訊,請參閱 ASP.NET Core 文件中的記錄篩選For more information, see Log filtering in the ASP.NET Core documentation.
主控台console n/an/a console記錄設定。The console logging setting.
applicationInsightsapplicationInsights n/an/a applicationInsights 設定。The applicationInsights setting.

主控台console

此設定是 logging 的子系。This setting is a child of logging. 它會在非處於偵錯模式時控制主控台記錄。It controls the console logging when not in debugging mode.

{
    "logging": {
    ...
        "console": {
          "isEnabled": "false"
        },
    ...
    }
}
屬性Property 預設Default 描述Description
isEnabledisEnabled false 啟用或停用主控台記錄。Enables or disables console logging.

queuesqueues

可在儲存體佇列觸發程序和繫結中找到組態設定。Configuration settings can be found in Storage queue triggers and bindings.

sendGridsendGrid

可在 SendGrid 觸發程序和繫結中找到組態設定。Configuration setting can be found in SendGrid triggers and bindings.

serviceBusserviceBus

可在服務匯流排觸發程序和繫結中找到組態設定。Configuration setting can be found in Service Bus triggers and bindings.

singletonsingleton

Singleton 鎖定行為的組態設定。Configuration settings for Singleton lock behavior. 如需詳細資訊,請參閱單一支援的 GitHub 問題For more information, see GitHub issue about singleton support.

{
    "singleton": {
      "lockPeriod": "00:00:15",
      "listenerLockPeriod": "00:01:00",
      "listenerLockRecoveryPollingInterval": "00:01:00",
      "lockAcquisitionTimeout": "00:01:00",
      "lockAcquisitionPollingInterval": "00:00:03"
    }
}
屬性Property 預設Default 描述Description
lockPeriodlockPeriod 00:00:1500:00:15 取得函式層級鎖定的期間。The period that function level locks are taken for. 鎖定會自動更新。The locks auto-renew.
listenerLockPeriodlistenerLockPeriod 00:01:0000:01:00 接聽程式鎖定所需的期間。The period that listener locks are taken for.
listenerLockRecoveryPollingIntervallistenerLockRecoveryPollingInterval 00:01:0000:01:00 啟動時無法取得接聽程式鎖定時,用於接聽程式鎖定復原的時間間隔。The time interval used for listener lock recovery if a listener lock couldn't be acquired on startup.
lockAcquisitionTimeoutlockAcquisitionTimeout 00:01:0000:01:00 執行階段將嘗試取得鎖定的時間量上限。The maximum amount of time the runtime will try to acquire a lock.
lockAcquisitionPollingIntervallockAcquisitionPollingInterval n/an/a 鎖定取得嘗試之間的間隔。The interval between lock acquisition attempts.

版本version

目標為 v2 執行階段的函數應用程式必須要有 "version": "2.0" 版本字串。The version string "version": "2.0" is required for a function app that targets the v2 runtime.

watchDirectorieswatchDirectories

應該監視其變更的一組共用程式碼目錄A set of shared code directories that should be monitored for changes. 請確定,這些目錄中的程式碼變更時,函式會反映變更。Ensures that when code in these directories is changed, the changes are picked up by your functions.

{
    "watchDirectories": [ "Shared" ]
}

managedDependencymanagedDependency

受控相依性是一項預覽功能, 目前僅支援以 PowerShell 為基礎的函式。Managed dependency is a preview feature that is currently only supported with PowerShell based functions. 它可讓服務自動管理相依性。It enables dependencies to be automatically managed by the service. 當 enabled 屬性設定為 true 時, 將會處理.psd1檔案。When the enabled property is set to true, the requirements.psd1 file will be processed. 發行任何次要版本時, 將會更新相依性。Dependencies will be updated when any minor versions are released.

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

後續步驟Next steps