Azure Functions 2.x 和更新版本的 host.json 參考 (機器翻譯)

host.json 中繼資料檔案所包含的設定選項會影響函數應用程式執行個體的所有函數。 本文列出從 Azure Functions 執行階段 2.x 版開始可用的設定。

注意

本文適用於 Azure Functions 2.x 和更新版本。 有關 Functions 1.x 中 host.json 的參考,請參閱適用於 Azure Functions 1.x 的 host.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": "[1.*, 2.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"
    },
    "watchDirectories": [ "Shared", "Test" ],
    "watchFiles": [ "myFile.txt" ]
}

本文的下列各節說明每個最上層屬性。 除非另有說明,否則全部都是選擇項目。

aggregator

指定計算 Application Insights 的計量時彙總多少函式引動過程。

{
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    }
}
屬性 預設 描述
batchSize 1000 要彙總的要求數目上限。
flushTimeout 00:00:30 要彙總的最長期間。

達到兩個限制的第一個限制時,會彙總函式引動過程。

applicationInsights

此設定是 logging 的子系。

控制 Application Insights 的選項,包括取樣選項

如需完整的 JSON 結構,請參閱先前的範例 host.json 檔案

注意

記錄取樣可能會造成一些執行不會顯示在 Application Insights 監視器刀鋒視窗。 若要避免記錄取樣,請將 excludedTypes: "Request" 新增至 samplingSettings 值。

屬性 預設 描述
samplingSettings n/a 請參閱 applicationInsights.samplingSettings
dependencyTrackingOptions n/a 請參閱 applicationInsights.dependencyTrackingOptions
enableLiveMetrics true 啟用即時計量收集。
enableDependencyTracking true 啟用相依性追蹤。
enablePerformanceCountersCollection true 啟用 Kudu 效能計數器收集。
liveMetricsInitializationDelay 00:00:15 僅供內部使用。
httpAutoCollectionOptions n/a 請參閱 applicationInsights.HTTPAutoCollectionOptions
snapshotConfiguration n/a 請參閱 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 不要進行取樣的分號分隔類型清單。 可辨識的類型為:DependencyEventExceptionPageViewRequestTrace。 會傳送所指定類型的所有執行個體;會針對未指定的類型進行取樣。
includedTypes null 您想要取樣之類型的分號分隔清單;空白清單表示所有類型。 excludedTypes 中所列類型會覆寫此處所列的類型。 可辨識的類型為:DependencyEventExceptionPageViewRequestTrace。 會取樣所指定類型的執行個體;會針對未指定或隱含的類型進行傳輸,而不會取樣。

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 快照偵錯工具或檢視快照集的問題進行疑難排解

屬性 預設 描述
agentEndpoint null 用來連線到 Application Insights 快照偵錯工具服務的端點。 如果為 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 針對單一問題收集的快照集數目上限,範圍從一到 999。 問題可能被視為應用程式中的個別擲回陳述式。 一旦針對問題收集的快照集數目達到此值,在重設問題計數器 (請見 problemCounterResetInterval) 並再次達到 thresholdForSnapshotting 限制之前,將不會再針對該問題收集快照集。
problemCounterResetInterval 24:00:00 重設問題計數器的頻率 (範圍從一分鐘到七天)。 達到此間隔時,所有問題計數都會重設為零。 已達到執行快照集閾值的現有問題,但尚未產生 maximumSnapshotsRequired 中的快照集數目,仍會保持作用中狀態。
provideAnonymousTelemetry true 判斷是否要將匿名使用方式和錯誤遙測傳送給 Microsoft。 如果您連絡 Microsoft 以協助針對快照偵錯工具的問題進行疑難排解,可能會使用此遙測。 其也可用來監視使用方式模式。
reconnectInterval 00:15:00 我們重新連線到快照偵錯工具端點的頻率。 允許的範圍是一分鐘到一天。
shadowCopyFolder null 指定要用於陰影複製二進位的資料夾。 如果未設定,則會依序嘗試下列環境變數所指定的資料夾:Fabric_Folder_App_Temp、LOCALAPPDATA、APPDATA、TEMP。
shareUploaderProcess true 如果為 true,則只有一個 SnapshotUploader 執行個體會針對共用 InstrumentationKey 的多個應用程式收集並上傳快照集。 如果設定為 false,SnapshotUploader 對每個 (ProcessName、InstrumentationKey) 元組是唯一的。
snapshotInLowPriorityThread true 判斷是否要在低 IO 優先順序執行緒中處理快照集。 建立快照集是快速的作業,但為了將快照集上傳至快照偵錯工具服務,必須先將快照集寫入磁碟做為小型傾印。 這會發生在 SnapshotUploader 程序中。 將此值設定為 true 會使用低優先順序 IO 來寫入小型傾印,而不會與您的應用程式競爭資源。 將此值設定為 false 會加快小型傾印建立的速度,但代價是降低應用程式的速度。
snapshotsPerDayLimit 30 一天 (24 小時) 允許的快照集數目上限。 也會在 Application Insights 服務端強制執行此限制。 每個應用程式 (也就是每個檢測金鑰) 上傳速率限制為每天 50 個。 此值有助於防止建立最終會在上傳期間遭到拒絕的其他快照集。 值為零會完全移除限制,不建議這麼做。
snapshotsPerTenMinutesLimit 1 10 分鐘中允許的快照集數目上限。 雖然此值沒有上限,但在生產工作負載增加此值時請小心,因為其可能會影響應用程式的效能。 建立快照集的速度很快,但建立快照集的小型傾印並將其上傳至快照偵錯工具服務是一項較慢的作業,從而與您的應用程式競爭資源 (CPU 和 I/O)。
tempFolder null 指定要寫入小型傾印和上傳程式記錄檔的資料夾。 如果未設定,則會使用 %TEMP%\Dumps
thresholdForSnapshotting 1 Application Insights 在要求快照集之前,必須看到例外狀況的次數。
uploaderProxy null 覆寫快照集上傳程式程序中使用的 Proxy 伺服器。 如果您的應用程式透過 Proxy 伺服器連線到網際網路,您可能需要使用此設定。 快照集收集器會在應用程式的程序中執行,並使用相同的 Proxy 設定。 不過,快照集上傳程式會以個別的程序執行,而且您可能需要手動設定 Proxy 伺服器。 如果此值為 Null,則快照集收集器會藉由檢查 System.Net.WebRequest.DefaultWebProxy 並將值傳遞至快照集上傳程式,嘗試自動偵測 Proxy 的位址。 如果此值不是 Null,則不會使用自動偵測,而且此處指定的 Proxy 伺服器將會用於快照集上傳程式。

Blob

可在儲存體 blob 觸發程序和繫結中找到設定。

console

此設定是 logging 的子系。 它會在非處於偵錯模式時控制主控台記錄。

{
    "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 n/a 要啟動為自訂處理常式程序的可執行檔。 使用自訂處理常式且其值與函數應用程式根是相對時,這是必要的設定。
workingDirectory 函數應用程式根 要在其中啟動自訂處理常式程序的工作目錄。 其是選擇性設定,其值與函數應用程式根是相對的。
引數 n/a 要傳遞至自訂處理常式程序的命令列引數陣列。
enableForwardingHttpRequest false 如果設定,則都會向只包含 HTTP 觸發程序和 HTTP 輸出的所有函數轉送原始 HTTP 要求,而不是自訂處理常式要求承載

durableTask

可在 Durable Functions 的繫結中找到組態設定。

並行

啟用函式應用程式中特定系結的動態並行。 如需詳細資訊,請參閱 動態並行

    { 
        "concurrency": { 
            "dynamicConcurrencyEnabled": true, 
            "snapshotPersistenceEnabled": true 
        } 
    } 
屬性 預設 描述
dynamicConcurrencyEnabled false 針對此功能支援的所有觸發程式啟用動態並行行為,此功能預設為關閉。
snapshotPersistenceEnabled true 學習的並行值會定期保存到儲存體,讓新的實例從這些值開始,而不是從 1 開始,而且必須重做學習。

eventHub

可在事件中樞觸發程序和繫結中找到組態設定。

擴充功能

傳回包含所有繫結特定設定 (例如 httpeventHub) 之物件的屬性。

extensionBundle

延伸模組搭售方案可讓您將一組相容的函數繫結延伸模組新增至函數應用程式。 若要深入瞭解,請參閱本地開發的延伸模組搭售方案

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

extensionBundle 中有下列屬性可供使用:

屬性 描述
id Microsoft Azure 函式擴充功能套件組合的命名空間。
version 要安裝的套件組合版本。 函式執行階段一律會挑選版本範圍或間隔所定義的最大允許版本。 上述版本值允許 3.3.0 版本以上的所有搭售方案版本,但不包括 4.0.0。 如需詳細資訊,請參閱指定版本範圍的間隔標記法

functions

工作主機所執行的函式清單。 空陣列表示已執行所有函式。 預定只能在本機執行時使用。 在 Azure 的函數應用程式中,您應該改為依照如何停用 Azure Functions 中的函式中的步驟來停用特定函式,而不是使用此設定。

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

functionTimeout

指出所有函式執行的逾時持續時間。 其會遵循時間範圍字串格式。

方案類型 預設 (分鐘) 最大 (分鐘)
耗用量 5 10
Premium1 30 -1 (unbounded)2
專用 (App Service) 30 -1 (unbounded)2

1 進階計畫執行只保證 60 分鐘,但技術上未繫結。
2-1 的值表示未繫結的執行,但建議保留固定上限。

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

healthMonitor

主機健康情況監視器的組態設定。

{
    "healthMonitor": {
        "enabled": true,
        "healthCheckInterval": "00:00:10",
        "healthCheckWindow": "00:02:00",
        "healthCheckThreshold": 6,
        "counterThreshold": 0.80
    }
}
屬性 預設 描述
已啟用 true 指定是否已啟用此功能。
healthCheckInterval 10 秒 定期背景健康情況檢查之間的時間間隔。
healthCheckWindow 2 分鐘 healthCheckThreshold 設定搭配使用的滑動時間範圍。
healthCheckThreshold 6 在主機回收起始之前,健康情況檢查可以失敗的最大次數。
counterThreshold 0.80 系統會將效能計數器視為狀況不良的閾值。

http

可在 HTTP 觸發程序和繫結中找到組態設定。

logging

控制函數應用程式 (包括 Application Insights) 的記錄行為。

"logging": {
    "fileLoggingMode": "debugOnly",
    "logLevel": {
      "Function.MyFunction": "Information",
      "default": "None"
    },
    "console": {
        ...
    },
    "applicationInsights": {
        ...
    }
}
屬性 預設 描述
fileLoggingMode debugOnly 定義已啟用何種檔案記錄層級。 選項為 neveralwaysdebugOnly
logLevel n/a 為應用程式中的函式定義記錄類別篩選的物件。 這可讓您篩選特定函數的記錄。 如需詳細資訊,請參閱設定記錄等級
console n/a 主控台記錄設定。
applicationInsights n/a applicationInsights 設定。

managedDependency

受控相依性是目前僅支援以 PowerShell 為基礎函數的功能。 其可讓服務自動管理相依性。 當 enabled 屬性設定為 true 時,便會處理 requirements.psd1 檔案。 發行任何次要版本時,就會更新相依性。 如需詳細資訊,請參閱 PowerShell 文章中的受控相依性

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

queues

可在儲存體佇列觸發程序和繫結中找到組態設定。

sendGrid

可在 SendGrid 觸發程序和繫結中找到組態設定。

serviceBus

可在服務匯流排觸發程序和繫結中找到組態設定。

singleton

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 n/a 鎖定取得嘗試之間的間隔。

version

這個值表示 host.json 的結構描述版本。 目標為第 2 版執行階段或更新版本的函數應用程式必須要有 "version": "2.0" 版本字串。 第 2 版與第 3 版之間沒有 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 Insight 取樣。 如果您將本地 host.json 檔案變更為停用 Application Insights,可能會在部署期間將這項變更推送至生產應用程式。 若要這樣做,更安全的方式是改為像 "AzureFunctionsJobHost__logging__applicationInsights__samplingSettings__isEnabled":"false"local.settings.json 檔案中一樣建立應用程式設定。 您可以在下列 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命名慣例。 當專案結構包含陣列時,數值陣列索引應該視為這個路徑中的其他元素名稱。 如需詳細資訊,請參閱 環境變數的命名

後續步驟