適用於 Azure Functions 1.x 的 host.json 參考

發行項
03/11/2024

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 服務時函式所使用的連線模式。選項為 `Direct` 和 `Gateway`
通訊協定	Https	連線到 Azure Cosmos DB 服務時函式所使用的連線通訊協定。請參閱此處以了解這兩種模式
leasePrefix	n/a	要在應用程式的所有函式上使用的租用前置詞。

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.jso 設定的根目錄中，而不是在 [延伸模組] 下的欄位。

Durable Functions 2.x
Durable Functions 1.x

{
 "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,
      "useTablePartitionManagement": false,
      "workItemQueueVisibilityTimeout": "00:05:00",
    },
    "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",
          "Pending",
          "Failed",
          "Terminated"
        ]
      }
    },
    "maxConcurrentActivityFunctions": 10,
    "maxConcurrentOrchestratorFunctions": 10,
    "extendedSessionsEnabled": false,
    "extendedSessionIdleTimeoutInSeconds": 30,
    "useAppLease": true,
    "useGracefulShutdown": false,
    "maxEntityOperationBatchSize": 50,
    "storeInputsInOrchestrationHistory": false
  }
 }
}

{
  "extensions": {
    "durableTask": {
      "hubName": "MyTaskHub",
      "controlQueueBatchSize": 32,
      "partitionCount": 4,
      "controlQueueVisibilityTimeout": "00:05:00",
      "workItemQueueVisibilityTimeout": "00:05:00",
      "maxConcurrentActivityFunctions": 10,
      "maxConcurrentOrchestratorFunctions": 10,
      "maxQueuePollingInterval": "00:00:30",
      "azureStorageConnectionStringName": "AzureWebJobsStorage",
      "trackingStoreConnectionStringName": "TrackingStorage",
      "trackingStoreNamePrefix": "DurableTask",
      "traceInputsAndOutputs": false,
      "logReplayEvents": false,
      "eventGridTopicEndpoint": "https://topic_name.westus2-1.eventgrid.azure.net/api/events",
      "eventGridKeySettingName":  "EventGridKey",
      "eventGridPublishRetryCount": 3,
      "eventGridPublishRetryInterval": "00:00:30",
      "eventGridPublishEventTypes": ["Started", "Completed", "Failed", "Terminated"]
    }
  }
}

工作中樞名稱必須以字母開頭，且只包含字母和數字。如果未指定，函式應用程式的預設工作中樞名稱為 TestHubName。如需詳細資訊，請參閱工作中樞。

屬性	預設	描述
hubName	TestHubName (如果使用 Durable Functions 1.x，則為 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」。較高的值可能會導致訊息處理延遲較高。較低的值會因為儲存體交易增加而導致儲存成本較高。
connectionName (2.7.0 和更新版本) connectionStringName (2.x) azureStorageConnectionStringName (1.x)	AzureWebJobsStorage	應用程式設定或設定集合的名稱，該名稱會指定連線到基礎 Azure 儲存體資源的方式。提供單一應用程式設定時，它應該是 Azure 儲存體連接字串。
trackingStoreConnectionName (2.7.0 和更新版本) trackingStoreConnectionStringName		指定如何連線到記錄和執行個體表格的應用程式設定或設定集合名稱。提供單一應用程式設定時，它應該是 Azure 儲存體連接字串。如果未指定，則會使用 `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	如果發佈到 Event Grid 主題失敗，重試的次數。
eventGridPublishRetryInterval	5 分鐘	「事件方格」會以 hh:mm:ss 格式發佈重試間隔。
eventGridPublishEventTypes		要發佈到事件方格的事件類型清單。如果未指定，則會發佈所有事件種類。允許的值包括 `Started`、`Completed`、`Failed` 或 `Terminated`。
useAppLease	true	設定為 `true` 時，應用程式必須在處理工作中樞訊息之前，取得應用程式層級的 Blob 租用。如需詳細資訊，請參閱災害復原和異地分佈文件。從 v2.3.0 開始可供使用。
useLegacyPartitionManagement	false	設定為 `false` 時，會使用資料分割管理演算法，以降低相應放大時重複函式執行的可能性。從 v2.3.0 開始可供使用。
useTablePartitionManagement	false	當設為 `true` 時，會使用專為降低 Azure 儲存體 V2 帳戶成本而設計的分割區管理演算法。從 v2.10.0 開始可供使用。這項功能目前處於預覽狀態，但尚未與取用方案相容。
useGracefulShutdown	false	(預覽) 啟用正常關機以減少主機關機讓內含式函式執行失敗的機會。
maxEntityOperationBatchSize(2.6.1)	使用量方案：50 專用/進階方案：5000	以批次方式處理的實體作業數目上限。如果上限設為 1，則會停用批次處理，而且每個作業訊息都會由個別的函式引動來處理。
storeInputsInOrchestrationHistory	false	當設為 `true` 時，會指示 Durable Task Framework 將活動輸入儲存在歷程記錄資料表中。這可讓您在查詢協調流程歷程記錄時顯示活動函式輸入。

上述許多設定適用於將效能最佳化。如需詳細資訊，請參閱效能和級別。

eventHub

事件中樞觸發程序和繫結的組態設定。

functions

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

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

functionTimeout

指出所有函式的逾時持續期間。在無伺服器的使用情況方案中，有效範圍是從 1 秒到 10 分鐘，而預設值是 5 分鐘。在 App Service 方案中沒有整體限制，而且預設值為 Null，這表示沒有逾時。

{
    "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 觸發程序和繫結的組態設定。

{
    "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

作業主機的唯一識別碼。可以是已移除虛線的小寫 GUID。在本機執行時為必要項目。在 Azure 中執行時，建議您不要設定識別碼值。當省略 id 時，在 Azure 中會自動產生識別碼。

如果您在多個函數應用程式中共用儲存體帳戶，請確定每個函數應用程式具有不同的 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 檔案中，所有開頭為 "Host.Aggregator" 的類別都會記錄在 `Information` 層級。所有開頭為 "Host" 的其他類別 (例如 "Host.Executor") 都會記錄於 `Error` 層級。

佇列

儲存體佇列觸發程序和繫結的組態設定。

{
    "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	n/a	基礎 ServiceBusReceiver 將使用的預設 PrefetchCount。
autoRenewTimeout	00:05:00	將自動更新訊息鎖定的最大持續時間。
autoComplete	true	若為真，觸發程序會在作業成功執行時，自動完成訊息處理。若為偽，則函式在傳回之前，必須負責完成訊息。

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

tracing

1.x 版

使用 TraceWriter 物件所建立記錄的組態設定。若要深入了解，請參閱 [C# 記錄]。

{
    "tracing": {
      "consoleLevel": "verbose",
      "fileLoggingMode": "debugOnly"
    }
}

屬性	預設	描述
consoleLevel	info	主控台記錄的追蹤層級。選項為：`off`、`error`、`warning`、`info` 和 `verbose`。
fileLoggingMode	debugOnly	檔案記錄的追蹤層級。選項為 `never`、`always`、`debugOnly`。

watchDirectories

應該監視其變更的一組共用程式碼目錄。請確定，這些目錄中的程式碼變更時，函式會反映變更。

{
    "watchDirectories": [ "Shared" ]
}

下一步

了解如何更新 host.json 檔案

環境變數中的保存設定