referência host.json para o Azure Functions 1.x

  • Artigo

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

Nota

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

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

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

Exemplo de arquivo host.json

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 a seguir deste artigo explicam cada propriedade de nível superior. Todos são opcionais, salvo indicação em 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 Predefinição Descrição
batchSize 1000 Número máximo de pedidos a agregar.
flushTimeout 00:00:30 Período máximo de tempo para agregar.

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 Predefinição Descrição
isEnabled verdadeiro Habilita ou desabilita a amostragem.
maxTelemetryItemsPerSecond 5 O limiar a partir do qual se inicia a amostragem.

DocumentDB

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

{
    "documentDB": {
        "connectionMode": "Gateway",
        "protocol": "Https",
        "leaseOptions": {
            "leasePrefix": "prefix1"
        }
    }
}
Propriedade Predefinição Descrição
Modo Gateway Gateway O modo de conexão usado pela função ao se conectar ao serviço Azure Cosmos DB. As opções são Direct e Gateway
Protocolo Disponível em: O protocolo de conexão usado pela função ao se conectar ao serviço Azure Cosmos DB. Leia aqui uma explicação de ambos os modos
leasePrefix n/d Prefixo de concessão para usar em todas as funções em um aplicativo.

durávelTarefa

Definições de configuração para funções duráveis.

Nota

Todas as versões principais do Durable Functions são suportadas em todas as versões do tempo de execução do Azure Functions. No entanto, o esquema da configuração host.json é ligeiramente diferente, dependendo da versão do tempo de execução do Azure Functions e da versão da extensão Durable Functions que você usa. Os exemplos a seguir são para 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 deve ir 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",
          "Pending",
          "Failed",
          "Terminated"
        ]
      }
    },
    "maxConcurrentActivityFunctions": 10,
    "maxConcurrentOrchestratorFunctions": 10,
    "extendedSessionsEnabled": false,
    "extendedSessionIdleTimeoutInSeconds": 30,
    "useAppLease": true,
    "useGracefulShutdown": false,
    "maxEntityOperationBatchSize": 50,
    "storeInputsInOrchestrationHistory": false
  }
 }
}

Os nomes do hub de tarefas devem começar com uma letra e consistir apenas em letras e números. Se não for especificado, o nome do hub de tarefa padrão para um aplicativo de função é TestHubName. Para obter mais informações, consulte Hubs de tarefas.

Propriedade Predefinição Descrição
hubName TestHubName (DurableFunctionsHub se estiver usando Durable Functions 1.x) Nomes de hub de tarefas alternativos podem ser usados para isolar vários aplicativos de Funções Duráveis uns dos outros, mesmo que estejam usando o mesmo back-end de armazenamento.
controlQueueBatchSize 32 O número de mensagens a serem extraídas da fila de controle de cada 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 da fila de controle que podem ser armazenadas em buffer na memória de cada vez, momento em que o dispatcher aguardará antes de dequeuar quaisquer mensagens adicionais.
partitionCount 4 A contagem de partições para a fila de controle. Pode ser um número inteiro positivo entre 1 e 16.
controlQueueVisibilityTimeout 5 minutos O tempo limite de visibilidade das mensagens da fila de controle desfileiradas.
workItemQueueVisibilityTimeout 5 minutos O tempo limite de visibilidade das mensagens da fila de itens de trabalho sem fila.
maxConcurrentActivityFunctions Plano de consumo: 10
Plano dedicado/Premium: 10X o número de processadores na máquina 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: 10X o número de processadores na máquina atual		 O número máximo de funções do orchestrator que podem ser processadas simultaneamente em uma única instância de host.
maxQueuePollingInterval 30 segundos O controle máximo e o intervalo de sondagem da fila de itens de trabalho 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 mais altos devido ao aumento das transações de armazenamento.
connectionName (2.7.0 e posterior)
connectionStringName (2.x)
azureStorageConnectionStringName (1.x)		 AzureWebJobsStorage O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar aos recursos subjacentes do Armazenamento do Azure. Quando uma única configuração de aplicativo é fornecida, ela deve ser 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 coleção de configurações que especifica como se conectar às tabelas Histórico e Instâncias. Quando uma única configuração de aplicativo é fornecida, ela deve ser uma cadeia de conexão do Armazenamento do Azure. Se não for especificado, a connectionStringName conexão (Durable 2.x) ou azureStorageConnectionStringName (Durable 1.x) será usada.
trackingStoreNamePrefix O prefixo a ser usado para as tabelas History e Instances quando trackingStoreConnectionStringName for especificado. Se não estiver definido, o valor do prefixo padrão será DurableTask. Se trackingStoreConnectionStringName não for especificado, as tabelas Histórico e Instâncias usarão o valor como seu prefixo hubName e qualquer configuração para trackingStoreNamePrefix será ignorada.
traceInputsAndOutputs false Um valor que indica se as entradas e saídas de chamadas de função devem ser rastreadas. O comportamento padrão ao rastrear 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 informações mínimas sobre a aparência das entradas e saídas sem inchar os logs ou expor inadvertidamente informações confidenciais. Definir essa propriedade como true faz com que o log de função padrão registre todo o conteúdo de entradas e saídas de função.
traceReplayEvents false Um valor que indica se os eventos de repetição de orquestração devem ser gravados no Application Insights.
eventGridTopicEndpoint A URL de um ponto de extremidade de tópico personalizado da Grade de Eventos do Azure. Quando essa propriedade é definida, os eventos de notificação do ciclo de vida da orquestração são publicados nesse ponto de extremidade. Esta propriedade suporta a resolução de Configurações do aplicativo.
eventGridKeySettingName O nome da configuração do aplicativo que contém a chave usada para autenticação com o tópico personalizado da Grade de Eventos do Azure em EventGridTopicEndpoint.
eventGridPublishRetryCount 0 O número de vezes a tentar novamente se a publicação no Tópico da Grade de Eventos falhar.
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 especificado, todos os tipos de evento serão publicados. Os valores permitidos incluem Started, , Completed, FailedTerminated.
useAppLease verdadeiro Quando definido como true, os aplicativos exigirão a aquisição de uma concessão de blob no nível do aplicativo antes de processar mensagens do hub de tarefas. Para obter mais informações, consulte a documentação de recuperação de desastres e distribuição geográfica. Disponível a partir da v2.3.0.
useLegacyPartitionManagement false Quando definido como false, usa um algoritmo de gerenciamento de partições que reduz a possibilidade de execução de função duplicada ao dimensionar. Disponível a partir da v2.3.0.
useTablePartitionManagement false Quando definido como true, usa um algoritmo de gerenciamento de partições projetado para reduzir custos para contas do Armazenamento do Azure V2. Disponível a partir da v2.10.0. Esta funcionalidade está atualmente em pré-visualização e ainda não é compatível com o plano de Consumo.
useGracefulShutdown false (Pré-visualização) Habilite o desligamento normal para reduzir a chance de desligamentos de host falharem nas 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 envio em lote será desativado e cada mensagem de operação será processada por uma chamada de função separada.
storeInputsInOrchestrationHistory false Quando definido como true, informa o Durable Task Framework 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 são para otimizar o desempenho. Para obter mais informações, consulte Desempenho e escala.

Hub de eventos

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

functions

Uma lista de funções que o host de trabalho executa. Uma matriz vazia significa executar todas as funções. Destina-se a ser usado apenas quando executado localmente. Em aplicativos de função 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 do Serviço de Aplicativo, não há limite geral e o padrão é null, o que indica que não há tempo limite.

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

monitor de saúde

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

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

http

Definições de configuração para gatilhos e ligações http.

{
    "http": {
        "routePrefix": "api",
        "maxOutstandingRequests": 200,
        "maxConcurrentRequests": 100,
        "dynamicThrottlesEnabled": true
    }
}
Propriedade Predefinição Descrição
dynamicThrottlesEnabled false Quando habilitada, essa configuração faz com que o pipeline de processamento de solicitações verifique periodicamente os contadores de desempenho do sistema, como conexões/threads/processos/memória/cpu/etc. e, se algum desses contadores estiver acima de um limite alto interno (80%), as solicitações serão rejeitadas com uma resposta 429 "Muito ocupado" até que o(s) contador(es) retorne(m) aos níveis normais.
maxConcurrentRequests ilimitado (-1) O número máximo de funções HTTP que serão executadas em paralelo. Permite-lhe controlar a simultaneidade, o que pode ajudar a gerir a utilização de recursos. Por exemplo, você pode ter uma função HTTP que usa muitos recursos do sistema (memória/cpu/soquetes) de tal forma que causa problemas quando a simultaneidade é muito alta. Ou você pode ter uma função que faz solicitações de saída para um serviço de terceiros, e essas chamadas precisam ser limitadas. Nestes casos, aplicar uma limitação aqui pode ajudar.
maxOutstandingRequests ilimitado (-1) O número máximo de solicitações pendentes que são mantidas em um determinado momento. Esse limite inclui solicitações que estão na fila, mas não começaram a ser executadas, e todas as execuções em andamento. Todas as solicitações recebidas acima desse limite são rejeitadas com uma resposta 429 "Muito ocupado". Isso permite que os chamadores empreguem estratégias de repetição baseadas no tempo e também ajuda você a controlar as latências máximas de solicitação. Isso controla apenas o enfileiramento que ocorre dentro do caminho de execução do host de script. Outras filas, como a fila de pedidos do ASP.NET, continuarão em vigor e não serão afetadas por esta definição.
routePrefix api O prefixo de rota que se aplica a todas as rotas. Use uma cadeia de caracteres vazia para remover o prefixo padrão.

ID

A ID exclusiva de um host de trabalho. Pode ser um GUID minúsculo com traços removidos. Necessário ao executar localmente. Ao executar no Azure, recomendamos que você não defina um valor de ID. Uma ID é gerada automaticamente no Azure quando id é omitida.

Se partilhar uma conta de Armazenamento em várias aplicações funcionais, certifique-se de que cada aplicação de função tem um idficheiro . Você pode omitir a id propriedade ou definir manualmente cada aplicativo de id função 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ção for expandido para várias instâncias. Se dois aplicativos de função compartilharem o mesmo id e cada um usar um gatilho de temporizador, apenas um temporizador será executado.

{
    "id": "9f4ea53c5136457d883d685e57164f08"
}

Registador

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 Predefinição Descrição
categoriaFiltrar n/d Especifica a filtragem por categoria
defaultLevel Informações Para quaisquer categorias não especificadas na matriz, envie logs neste nível e acima para o categoryLevels Application Insights.
categoriaNíveis n/d Uma matriz de categorias que especifica o nível mínimo de log a ser enviado ao Application Insights para cada categoria. A categoria especificada aqui controla todas as categorias que começam com o mesmo valor, e valores mais longos têm precedência. No arquivo host.json de exemplo anterior, todas as categorias que começam com "Host.Aggregator" registram no Information nível. Todas as outras categorias que começam com "Host", como "Host.Executor", registram no Error nível.

filas

Definições de configuração para gatilhos e associações de fila de armazenamento.

{
    "queues": {
      "maxPollingInterval": 2000,
      "visibilityTimeout" : "00:00:30",
      "batchSize": 16,
      "maxDequeueCount": 5,
      "newBatchThreshold": 8
    }
}
Propriedade Predefinição Descrição
maxPollingInterval 60000 O intervalo máximo em milissegundos entre as sondagens da fila.
visibilidadeTempo limite 0 O intervalo de tempo entre novas tentativas quando o processamento de uma mensagem falha.
batchSize 17 O número de mensagens de fila que o tempo de execução do Functions recupera simultaneamente e processa em paralelo. Quando o número que está sendo processado desce para o , o newBatchThresholdtempo de execução recebe outro lote e começa a processar essas mensagens. Assim, o número máximo de mensagens simultâneas sendo processadas por função é batchSize mais newBatchThreshold. Esse limite se aplica separadamente a cada função acionada por fila.

Se quiser evitar a execução paralela de mensagens recebidas em uma fila, você pode definir batchSize como 1. No entanto, essa configuração elimina a simultaneidade apenas enquanto seu aplicativo de função for executado em uma única máquina virtual (VM). Se o aplicativo de função for expandido para várias VMs, cada VM poderá 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 venenos.
newBatchThreshold Tamanho do lote/2 Sempre que o número de mensagens que estão sendo processadas simultaneamente é reduzido a esse número, o tempo de execução recupera outro lote.

SendGrid

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

{
    "sendGrid": {
        "from": "Contoso Group <admin@contoso.com>"
    }
}
Propriedade Predefinição Descrição
de n/d O endereço de e-mail do remetente em todas as funções.

serviceBus [en]

Definição de configuração para gatilhos e associações do Service Bus.

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

singleton

Definições de configuração para o comportamento de bloqueio Singleton. Para obter mais informações, consulte Problema do GitHub sobre suporte a singleton.

{
    "singleton": {
      "lockPeriod": "00:00:15",
      "listenerLockPeriod": "00:01:00",
      "listenerLockRecoveryPollingInterval": "00:01:00",
      "lockAcquisitionTimeout": "00:01:00",
      "lockAcquisitionPollingInterval": "00:00:03"
    }
}
Propriedade Predefinição Descrição
lockPeriod 00:00:15 O período durante o qual os bloqueios de nível de função são considerados. Os bloqueios renovam-se automaticamente.
ouvinteLockPeriod 00:01:00 O período pelo qual o ouvinte trava é tomado.
listenerLockRecoveryPollingInterval 00:01:00 O intervalo de tempo usado para a recuperação do bloqueio do ouvinte se um bloqueio do ouvinte não puder ser adquirido na inicialização.
lockAcquisitionTimeout 00:01:00 A quantidade máxima de tempo que o tempo de execução tenta adquirir um bloqueio.
lockAcquisitionPollingInterval n/d O intervalo entre as tentativas de aquisição de bloqueio.

rastreio

Versão 1.x

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

{
    "tracing": {
      "consoleLevel": "verbose",
      "fileLoggingMode": "debugOnly"
    }
}
Propriedade Predefinição Descrição
consoleLevel informação O nível de rastreamento para registro em log do console. As opções são: off, , , , infoerrorwarninge .verbose
fileLoggingMode debugOnly O nível de rastreamento para registro em log de arquivos. As opções são never, , alwaysdebugOnly.

watchDiretórios

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 são captadas pelas suas funções.

{
    "watchDirectories": [ "Shared" ]
}

Próximos passos

Saiba como atualizar o arquivo host.json

Persistir configurações em variáveis de ambiente