Referência de host.json para as funções do Azure 1.x

  • Artigo

O arquivo de metadados host.json contém opções de configuração que afetam todas as funções de uma instância de aplicativo de funções. Este artigo lista as configurações disponíveis para o runtime da versão 1.x. O esquema JSON está em http://json.schemastore.org/host.

Observação

Este artigo serve para o Azure Functions 1.x. Para obter uma referência de host.json no Functions 2.x e posterior, confira Referência de host.json para o Azure Functions 2.x.

Outras opções de configuração de aplicativo de funções são gerenciadas nas configurações de aplicativo.

Algumas configurações host.json são usadas apenas quando executadas localmente no arquivo local.settings.json.

Arquivo host.json de exemplo

Os seguintes arquivos host.json de exemplo têm todas as opções possíveis especificadas.

{
    "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" ],
}

As seções seguintes deste artigo explicam cada propriedade de nível superior. Todas são opcionais, a menos que seja indicado o contrário.

agregador

Especifica quantas invocações de função são agregadas ao calcular métricas para o Application Insights.

{
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    }
}
Propriedade Padrão Descrição
batchSize 1000 Número máximo de solicitações para agregação.
flushTimeout 00:00:30 Período de tempo máximo para agregação.

As invocações de função são agregadas quando o primeiro dos dois limites é atingido.

applicationInsights

Controla o recurso de amostragem no Application Insights.

{
    "applicationInsights": {
        "sampling": {
          "isEnabled": true,
          "maxTelemetryItemsPerSecond" : 5
        }
    }
}
Propriedade Padrão Descrição
isEnabled true Habilita ou desabilita a amostragem.
maxTelemetryItemsPerSecond 5 O limite em que a amostragem começa.

DocumentDB

Definições de configuração para o gatilho do Azure Cosmos DB e associações.

{
    "documentDB": {
        "connectionMode": "Gateway",
        "protocol": "Https",
        "leaseOptions": {
            "leasePrefix": "prefix1"
        }
    }
}
Propriedade Padrão Descrição
GatewayMode Gateway O modo de conexão usado pela função ao se conectar ao serviço do Azure Cosmos DB. As opções são Direct e Gateway
Protocolo Https O protocolo de conexão usado pela função ao se conectar ao serviço do Azure Cosmos DB. Leia aqui para obter uma explicação de ambos os modos
leasePrefix N/D Prefixo de concessão a ser usado em todas as funções em um aplicativo.

durableTask

Definições de configuração para Funções Duráveis.

Observação

Todas as versões principais das Durable Functions são compatíveis com todas as versões do Azure Functions Runtime. No entanto, o esquema da configuração host.json é ligeiramente diferente dependendo da versão do Azure Functions Runtime e da versão da extensão das Durable Functions que você usa. Os exemplos a seguir são referentes ao uso com o Azure Functions 2.0 e 3.0. Em ambos os exemplos, se você estiver usando o Azure Functions 1.0, as configurações disponíveis serão as mesmas, mas a seção "durableTask" do host.json deverá estar na raiz da configuração host.json, em vez de como um campo em "extensões".

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

Nomes de hubs de tarefas devem começar com uma letra e devem ser compostos somente por letras e números. Se não for especificado, o nome padrão do hub de tarefas para um aplicativo de função será TestHubName. Para obter mais informações, consulte Hubs de tarefas.

Propriedade Padrão Descrição
hubName TestHubName (DurableFunctionsHub se estiver usando o Durable Functions 1.x) Nomes alternativos para hub de tarefas podem ser usados para isolar vários aplicativos de Funções Duráveis uns dos outros, mesmo se eles estiverem usando o mesmo back-end de armazenamento.
controlQueueBatchSize 32 O número de mensagens para efetuar pull da fila de controle por vez.
controlQueueBufferThreshold Plano de consumo para Python: 32
Plano de consumo para JavaScript e C#: 128
Plano Dedicado/Premium: 256		 O número de mensagens de fila de controle que podem ser armazenadas em buffer na memória por vez. Nesse ponto, o dispatcher aguardará antes de retirar da fila qualquer mensagem adicional.
partitionCount 4 A contagem de partição para a fila de controle. Pode ser um número inteiro positivo entre 1 e 16.
controlQueueVisibilityTimeout 5 minutos O limite de tempo de visibilidade das mensagens de remoção da fila de controle.
workItemQueueVisibilityTimeout 5 minutos O limite de tempo de visibilidade das mensagens de remoção da fila de item de trabalho.
maxConcurrentActivityFunctions Plano de Consumo: 10
Plano Dedicado/Premium: dez vezes o número de processadores do computador atual		 O número máximo de funções de atividade que podem ser processadas simultaneamente em uma única instância de host.
maxConcurrentOrchestratorFunctions Plano de Consumo: 5
Plano Dedicado/Premium: dez vezes o número de processadores do computador atual		 O número máximo de funções do orquestrador que podem ser processadas simultaneamente em uma única instância do host.
maxQueuePollingInterval 30 segundos O intervalo de sondagem da fila de item de trabalho e de controle máximo no formato hh:mm:ss. Valores mais altos podem resultar em latências de processamento de mensagens mais altas. Valores mais baixos podem resultar em custos de armazenamento maiores devido a um maior número de transações de armazenamento.
connectionName (2.7.0 e posterior)
connectionStringName (2.x)
azureStorageConnectionStringName (1.x)		 AzureWebJobsStorage O nome de uma configuração de um aplicativo ou de uma coleção de configurações que especifica como se conectar aos recursos subjacentes do Armazenamento do Azure. Quando é informada uma configuração de aplicativo único, é necessário que ela seja uma cadeia de conexão do Armazenamento do Azure.
trackingStoreConnectionName (2.7.0 e posterior)
trackingStoreConnectionStringName		 O nome de uma configuração de aplicativo ou de uma coleção de configurações que especifica como se conectar às tabelas História e Instâncias. Quando é informada uma configuração de aplicativo único, é necessário que ela seja uma cadeia de conexão do Armazenamento do Azure. Se não for especificado, a conexão connectionStringName (Durable 2.x) ou azureStorageConnectionStringName (Durable 1.x) será usada.
trackingStoreNamePrefix O prefixo a ser usado para as tabelas Histórico e Instâncias quando trackingStoreConnectionStringName for especificado. Se não estiver definido, o valor de prefixo padrão será DurableTask. Se trackingStoreConnectionStringName não for especificado, as tabelas Histórico e Instâncias usarão o valor hubName como o prefixo e qualquer configuração de trackingStoreNamePrefix será ignorada.
traceInputsAndOutputs false Um valor que indica se as entradas e saídas de chamadas de função sertão rastreadas. O comportamento padrão durante o rastreamento de eventos de execução de função é incluir o número de bytes nas entradas e saídas serializadas para chamadas de função. Esse comportamento fornece um mínimo de informações sobre como são as entradas e saídas sem sobrecarregar os logs ou expor inadvertidamente informações confidenciais. A definição dessa propriedade como true faz com que o log de função padrão registre todo o conteúdo de entradas e saídas da função.
traceReplayEvents false Um valor que indica se é necessário gravar eventos de reprodução de orquestração para o Application Insights.
eventGridTopicEndpoint A URL de um ponto de extremidade de tópico personalizado da Grade de Eventos do Azure. Quando essa propriedade for definida, eventos de notificação de ciclo de vida de orquestração serão publicados para esse ponto de extremidade. Esta propriedade dá suporte à resolução de Configurações do Aplicativo.
eventGridKeySettingName O nome da configuração de aplicativo que contém a chave usada para autenticar com o tópico personalizado da Grade de Eventos do Azure em EventGridTopicEndpoint.
eventGridPublishRetryCount 0 O número de novas tentativas se a publicação no Tópico de Grade de Eventos falha.
eventGridPublishRetryInterval 5 minutos A Grade de Eventos publica o intervalo de repetição no formato hh:mm:ss.
eventGridPublishEventTypes Uma lista de tipos de eventos a serem publicados na Grade de Eventos. Se não for especificada, todos os tipos de evento serão publicados. Os valores permitidos incluem Started, Completed, Failed, Terminated.
useAppLease true Quando configurado como true, os aplicativos exigirão adquirir uma concessão de blob de nível de aplicativo antes de processar mensagens do hub de tarefas. Para obter mais informações, consulte a documentação recuperação de desastre e distribuição geográfica. Disponível a partir da v2.3.0.
useLegacyPartitionManagement false Quando definido como false, ele usa um algoritmo de gerenciamento de partição que reduz a possibilidade de execução de função duplicada ao expandir. Disponível a partir da v2.3.0.
useTablePartitionManagement falso Quando definido como true, usa um algoritmo de gerenciamento de partição projetado para reduzir os custos das contas do Armazenamento do Microsoft Azure V2. Disponível a partir da v2.10.0. Esse recurso está atualmente em versão prévia e ainda não é compatível com o plano de Consumo.
useGracefulShutdown false (Versão Prévia) Habilite o desligamento normal para reduzir a chance de desligamentos de host falharem em execuções de função em processo.
maxEntityOperationBatchSize(2.6.1) Plano de consumo: 50
Plano Dedicado/Premium: 5000		 O número máximo de operações de entidade que são processadas como um lote. Se definido como 1, o lote será desabilitado e cada mensagem de operação será processada por uma invocação de função separada.
storeInputsInOrchestrationHistory falso Quando definido como true, informa a Estrutura de Tarefas Duráveis para salvar entradas de atividade na tabela de histórico. Isso permite a exibição de entradas de função de atividade ao consultar o histórico de orquestração.

Muitas dessas configurações servem para otimizar o desempenho. Para obter mais informações, consulte Desempenho e escala.

eventHub

Definições de configuração para gatilhos e associações de Hub de Eventos.

funções

Uma lista de funções que o host de trabalho executa. Uma matriz vazia significa que todas as funções serão executadas. Para uso somente quando em execução localmente. Em aplicativos de funções no Azure, você deve seguir as etapas em Como desabilitar funções no Azure Functions para desabilitar funções específicas em vez de usar essa configuração.

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

functionTimeout

Indica a duração do tempo limite para todas as funções. Em um plano de Consumo sem servidor, o intervalo válido é de 1 segundo a 10 minutos e o valor padrão é 5 minutos. Em um Plano de Serviço de Aplicativo, não há limite geral e o valor padrão é nulo, o que indica que não há nenhum tempo limite.

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

healthMonitor

Definições de configuração para monitor de integridade de Host.

{
    "healthMonitor": {
        "enabled": true,
        "healthCheckInterval": "00:00:10",
        "healthCheckWindow": "00:02:00",
        "healthCheckThreshold": 6,
        "counterThreshold": 0.80
    }
}
Propriedade Padrão Descrição
Habilitado true Especifica se o recurso está habilitado.
healthCheckInterval 10 segundos O intervalo de tempo entre as verificações de integridade em segundo plano.
healthCheckWindow 2 minutos Uma janela de tempo deslizante usada com a configuração healthCheckThreshold.
healthCheckThreshold 6 Número máximo de vezes que a verificação de integridade pode falhar antes de uma reciclagem de host ser iniciada.
counterThreshold 0.80 O limite no qual um contador de desempenho será considerado não íntegro.

http

Parâmetros de configuração para gatilhos e associações http.

{
    "http": {
        "routePrefix": "api",
        "maxOutstandingRequests": 200,
        "maxConcurrentRequests": 100,
        "dynamicThrottlesEnabled": true
    }
}
Propriedade Padrão Descrição
dynamicThrottlesEnabled falso Quando habilitada, essa configuração faz com que o pipeline de processamento de solicitações verifique periodicamente contadores de desempenho do sistema, como connections/threads/processes/memory/cpu/etc. e, se qualquer um desses contadores ultrapassar um limite alto interno (80%), as solicitações serão rejeitadas com uma resposta "Muito ocupado" 429 até que os contadores retornem aos níveis normais.
maxConcurrentRequests não associado (-1) O número máximo de funções HTTP que serão executadas em paralelo. Isso permite controlar a simultaneidade, o que pode ajudar a gerenciar a utilização de recursos. Por exemplo, talvez você tenha uma função HTTP que use muitos recursos do sistema (memória/cpu/soquetes), de modo que ela causará problemas quando a simultaneidade for muito alta. Ou talvez você tenha uma função que faça solicitações de saída a um serviço de terceiro, e essas chamadas precisem ser limitadas por taxa. Nesses casos, aplicar uma limitação aqui pode ajudar.
maxOutstandingRequests não associado (-1) O número máximo de solicitações pendentes mantidas em um dado momento. Esse limite inclui solicitações que estão na fila, mas não iniciaram a execução, e qualquer execução em andamento. Quaisquer solicitações recebidas acima desse limite são rejeitadas com uma resposta "Muito ocupado" 429. Isso permite que os chamadores empreguem estratégias de repetição com base em tempo e também ajuda você a controlar as latências máximas de solicitação. Isso controla apenas o enfileiramento que ocorre no caminho de execução do host de script. Outras filas, como a fila de solicitação ASP.NET, ainda estarão vigor e não serão afetadas por essa configuração.
routePrefix api O prefixo da rota que se aplica a todas as rotas. Use uma cadeia de caracteres vazia para remover o prefixo padrão.

id

A ID exclusiva do host de trabalho. Pode ser uma GUID em letras minúsculas, sem traços. Obrigatório ao executar localmente. Ao executar no Azure, é recomendável que você não defina um valor de ID. Uma ID é gerada automaticamente no Azure quando id está omitido.

Se você compartilhar uma conta de Armazenamento em vários aplicativos de funções, verifique se cada aplicativo de função tem um id diferente. É possível omitir a propriedade id ou definir manualmente cada aplicativo de funções id para um valor diferente. O gatilho de temporizador usa um bloqueio de armazenamento para garantir que haverá apenas uma instância de temporizador quando um aplicativo de funções escalar horizontalmente para várias instâncias. Se dois aplicativos de funções compartilharem o mesmo id e cada um usar um gatilho de temporizador, somente um temporizador irá executar.

{
    "id": "9f4ea53c5136457d883d685e57164f08"
}

agente

Controla a filtragem de logs gravados por um objeto ILogger ou por context.log.

{
    "logger": {
        "categoryFilter": {
            "defaultLevel": "Information",
            "categoryLevels": {
                "Host": "Error",
                "Function": "Error",
                "Host.Aggregator": "Information"
            }
        }
    }
}
Propriedade Padrão Descrição
categoryFilter N/D Especifica a filtragem por categoria
defaultLevel Informações do Para as categorias não especificadas na matriz categoryLevels, envie logs nesse nível e acima para o Application Insights.
categoryLevels N/D Uma matriz de categorias que especifica o nível mínimo de logs que será enviado ao Application Insights para cada categoria. A categoria especificada aqui controla todas as categorias que começam com o mesmo valor, com precedência para os valores maiores. No arquivo de exemplo host.json anterior, todas as categorias que começam com o log "Host.Aggregator" no nível Information. Todas as outras categorias que começam com o log "Host", como "Host.Executor", no nível Error.

filas

Parâmetros de configuração para gatilhos e associações de Armazenamento.

{
    "queues": {
      "maxPollingInterval": 2000,
      "visibilityTimeout" : "00:00:30",
      "batchSize": 16,
      "maxDequeueCount": 5,
      "newBatchThreshold": 8
    }
}
Propriedade Padrão Descrição
maxPollingInterval 60000 O intervalo máximo em milissegundos entre as votações da fila.
visibilityTimeout 0 O intervalo de tempo entre as repetições quando o processamento de uma mensagem falha.
batchSize 16 O número de mensagens em fila que o runtime de Funções recupera simultaneamente e processa em paralelo. Quando o número que está sendo processado chega até newBatchThreshold, o runtime obtém outro lote e começa a processar as mensagens. Portanto, o número máximo de mensagens simultâneas que estão sendo processadas por função é batchSize mais newBatchThreshold. Esse limite se aplica separadamente a cada função acionada por fila.

Se quiser evitar uma execução paralela para mensagens recebidas em uma fila, é possível definir batchSize como 1. No entanto, essa configuração elimina a simultaneidade desde que seu aplicativo de função seja executado em uma única máquina virtual (VM). Se o aplicativo de função se expande para várias VMs, cada VM pode executar uma instância de cada função acionada por fila.

O máximo batchSize é 32.
maxDequeueCount 5 O número de vezes para tentar processar uma mensagem antes de movê-la para a fila de mensagens suspeitas.
newBatchThreshold batchSize/2 Sempre que o número de mensagens processadas simultaneamente chega a esse número, o runtime recupera outro lote.

SendGrid

Definição de configuração para a associação de saída SendGrind

{
    "sendGrid": {
        "from": "Contoso Group <admin@contoso.com>"
    }
}
Propriedade Padrão Descrição
de N/D Endereço de email do remetente em todas as funções.

serviceBus

Parâmetro de configuração para gatilhos e associações do Barramento de Serviço.

{ 
    "serviceBus": {
      "maxConcurrentCalls": 16,
      "prefetchCount": 100,
      "autoRenewTimeout": "00:05:00",
      "autoComplete": true
    }
}
Propriedade Padrão Descrição
maxConcurrentCalls 16 O número máximo de chamadas simultâneas para o retorno de chamada que a bomba de mensagens deve iniciar. Por padrão, o runtime do Functions processa várias mensagens simultaneamente. Para direcionar o runtime para processar uma única fila ou mensagem de tópico de cada vez, defina maxConcurrentCalls como 1.
prefetchCount N/D O PrefetchCount padrão que será usado pelo ServiceBusReceiver subjacente.
autoRenewTimeout 00:05:00 A duração máxima na qual o bloqueio de mensagem será renovado automaticamente.
autoComplete true Quando true, o gatilho conclui o processamento da mensagem automaticamente na execução bem-sucedida da operação. Quando false, é responsabilidade da função concluir a mensagem antes de retornar.

singleton

Parâmetro de configuração para o comportamento de bloqueio de Singleton. Para obter mais informações, consulte Problema com o GitHub referente ao suporte de singleton.

{
    "singleton": {
      "lockPeriod": "00:00:15",
      "listenerLockPeriod": "00:01:00",
      "listenerLockRecoveryPollingInterval": "00:01:00",
      "lockAcquisitionTimeout": "00:01:00",
      "lockAcquisitionPollingInterval": "00:00:03"
    }
}
Propriedade Padrão Descrição
lockPeriod 00:00:15 O período em que ocorrem os bloqueios de nível de função. Os bloqueios têm renovação automática.
listenerLockPeriod 00:01:00 O período em que ocorrem os bloqueios de ouvinte.
listenerLockRecoveryPollingInterval 00:01:00 O intervalo de tempo usado para a recuperação do bloqueio de ouvinte caso não tenha sido possível adquirir um bloqueio de ouvinte durante a inicialização.
lockAcquisitionTimeout 00:01:00 A quantidade máxima de tempo em que o runtime tenta adquirir um bloqueio.
lockAcquisitionPollingInterval N/D O intervalo entre as tentativas de aquisição de bloqueio.

tracing

Versão 1.x

Parâmetros de configuração para logs que você cria usando um objeto TraceWriter. Para saber mais, consulte [C# Logging].

{
    "tracing": {
      "consoleLevel": "verbose",
      "fileLoggingMode": "debugOnly"
    }
}
Propriedade Padrão Descrição
consoleLevel informações O nível de rastreamento para o registro em log no console. As opções são: off, error, warning, info e verbose.
fileLoggingMode debugOnly O nível de rastreamento para registros em log de arquivo. As opções são: never, always e debugOnly.

watchDirectories

Um conjunto de diretórios de código compartilhado que devem ser monitorados quanto a alterações. Garante que, quando o código nesses diretórios é alterado, as alterações sejam coletadas pelas funções.

{
    "watchDirectories": [ "Shared" ]
}

Próximas etapas

Saiba como atualizar o arquivo host.json

Persistir configurações em variáveis de ambiente