Referencia de host.json para Azure Functions 1.x

El archivo de metadatos host.json contiene las opciones de configuración global que afectan a todas las funciones de dicha instancia de aplicación de funciones. En este artículo se incluye una lista de las opciones de configuración disponibles para el entorno en tiempo de ejecución de la versión 1.x. El esquema JSON está en http://json.schemastore.org/host.

Nota

Este artículo trata sobre Azure Functions 1.x. Para obtener una referencia de host.json en Functions 2.x y versiones posteriores, consulte Referencia de host.json para Azure Functions 2.x.

Otras opciones de configuración de aplicación de función se administran en su configuración de la aplicación.

Algunas opciones de configuración de host.json solo se usan con la ejecución local en el archivo local.settings.json.

Archivo host.json de ejemplo

El siguiente archivo host.json de ejemplo tiene especificadas todas las opciones posibles.

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

Las siguientes secciones de este artículo explican cada propiedad de nivel superior. Todas son opcionales, a menos que se indique lo contrario.

aggregator

Especifica cuántas llamadas a funciones se agregan cuando se calculan las métricas para Application Insights.

{
    "aggregator": {
        "batchSize": 1000,
        "flushTimeout": "00:00:30"
    }
}
Propiedad Valor predeterminado Descripción
batchSize 1000 Número máximo de solicitudes para agregar.
flushTimeout 00:00:30 Período máximo de tiempo para agregar.

Las llamadas a funciones se agregan cuando se alcanza el primero de los dos límites.

applicationInsights

Controla la característica de muestreo de Application Insights.

{
    "applicationInsights": {
        "sampling": {
          "isEnabled": true,
          "maxTelemetryItemsPerSecond" : 5
        }
    }
}
Propiedad Valor predeterminado Descripción
isEnabled true Habilita o deshabilita el muestreo.
maxTelemetryItemsPerSecond 5 Umbral donde comienza el muestreo.

DocumentDB

Opciones de configuración para los desencadenadores y enlaces de Azure Cosmos DB.

{
    "documentDB": {
        "connectionMode": "Gateway",
        "protocol": "Https",
        "leaseOptions": {
            "leasePrefix": "prefix1"
        }
    }
}
Propiedad Valor predeterminado Descripción
GatewayMode Puerta de enlace Modo de conexión que usa la función al conectarse al servicio de Azure Cosmos DB. Las opciones son Direct y Gateway
Protocolo Https Protocolo de conexión que usa la función al conectarse al servicio de Azure Cosmos DB. Lea aquí para obtener una explicación de los dos modos
leasePrefix N/D Prefijo de concesión que se usará en todas las funciones de una aplicación.

durableTask

Configuración de Durable Functions.

Nota

Todas las versiones principales de Durable Functions son compatibles con todas las versiones del runtime de Azure Functions. Sin embargo, el esquema de la configuración de host.json es ligeramente diferente en función de la versión del runtime de Azure Functions y de la versión de la extensión de Durable Functions que se use. Los ejemplos siguientes son para Azure Functions 2.0 y 3.0. En ambos ejemplos, si se usa Azure Functions 1.0, la configuración disponible es la misma, pero la sección "durableTask" de host.json debería ir en la raíz de la configuración del archivo, en lugar de como un campo de "extensions".

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

Los nombres de la central de tareas deben empezar por una letra y estar formados únicamente por letras y números. Si no se especifica, el nombre predeterminado de la central de tareas de la aplicación de función es TestHubName. Para más información, consulte el artículo sobre las centrales de tareas.

Propiedad Valor predeterminado Descripción
hubName TestHubName (DurableFunctionsHub si usa Durable Functions 1.x) Se pueden usar nombres de central de tareas alternativos para aislar varias aplicaciones de Durable Functions unas de otras, incluso si usan el mismo back-end de almacenamiento.
controlQueueBatchSize 32 El número de mensajes que se van a extraer a la vez de la cola de control.
controlQueueBufferThreshold Plan de consumo para Python: 32
Plan de consumo para JavaScript y C#: 128
Plan dedicado/Premium: 256
Número de mensajes de la cola de control que se pueden almacenar en búfer en la memoria a la vez, momento en que el distribuidor esperará para quitar cualquier mensaje adicional de la cola.
partitionCount 4 El recuento de particiones para la cola de control. Puede ser un entero positivo comprendido entre 1 y 16.
controlQueueVisibilityTimeout 5 minutos El tiempo de espera de visibilidad de los mensajes de la cola de control quitados de la cola.
workItemQueueVisibilityTimeout 5 minutos El tiempo de espera de visibilidad de los mensajes de la cola de elementos de trabajo quitados de la cola.
maxConcurrentActivityFunctions Plan de consumo: 10
Plan dedicado/Premium: 10 veces el número de procesadores en la máquina actual
El número máximo de funciones de actividad que se pueden procesar simultáneamente en una única instancia de host.
maxConcurrentOrchestratorFunctions Plan de consumo: 5
Plan dedicado/Premium: 10 veces el número de procesadores en la máquina actual
El número máximo de funciones de Orchestrator que se pueden procesar simultáneamente en una única instancia de host.
maxQueuePollingInterval 30 segundos Intervalo de sondeo de cola de elementos de trabajo y control máximo en formato hh:mm:ss: . Los valores más altos pueden provocar mayores latencias de procesamiento de mensajes. Los valores más bajos pueden provocar mayores costos de almacenamiento debido a transacciones de almacenamiento mayor.
connectionName (2.7.0 y versiones posteriores)
connectionStringName (2.x)
azureStorageConnectionStringName (1.x)
AzureWebJobsStorage Nombre de una configuración de aplicación o de una colección de configuraciones que especifica cómo conectarse a los recursos subyacentes de Azure Storage. Cuando se proporciona una única configuración de aplicación, debe ser una cadena de conexión de Azure Storage.
trackingStoreConnectionName (2.7.0 y versiones posteriores)
trackingStoreConnectionStringName
Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a las tablas de historial e instancias. Cuando se proporciona una única configuración de aplicación, debe ser una cadena de conexión de Azure Storage. Si no se especifica, se usa las conexiones connectionStringName (Durable 2.x) o azureStorageConnectionStringName (Durable 1.x).
trackingStoreNamePrefix Prefijo que se usará para las tablas de historial e instancias cuando se especifica trackingStoreConnectionStringName. Si no se establece, el valor de prefijo predeterminado será DurableTask. Si no se especifica trackingStoreConnectionStringName, las tablas de historial e instancias usarán el valor hubName como prefijo y se pasarán por alto todos los valores de configuración de trackingStoreNamePrefix.
traceInputsAndOutputs false Un valor que indica si se realizará el seguimiento de las entradas y salidas de las llamadas de función. El comportamiento predeterminado al realizar el seguimiento de eventos de ejecución de funciones es incluir el número de bytes en las entradas y salidas serializadas de las llamadas de función. Este comportamiento proporciona información mínima sobre el aspecto de las entradas y salidas, sin sobredimensionar los registros o exponer por accidente información confidencial. Al establecer esta propiedad en true, el registro de funciones predeterminado registra todo el contenido de las entradas y salidas de función.
traceReplayEvents false Un valor que indica si se debe escribir eventos de reproducción de orquestación en Application Insights.
eventGridTopicEndpoint La dirección URL de un punto de conexión de tema personalizado de Azure Event Grid. Cuando se establece esta propiedad, se publican eventos de notificación del ciclo de vida de orquestación en este punto de conexión. Esta propiedad admite la resolución de la configuración de la aplicación.
eventGridKeySettingName El nombre de la configuración de aplicación que contiene la clave usada para autenticarse con el tema personalizado de Azure Event Grid en EventGridTopicEndpoint.
eventGridPublishRetryCount 0 El número de reintentos, si, al publicar en el tema de Event Grid, se produce un error.
eventGridPublishRetryInterval 5 minutos Event Grid publica el intervalo de reintento en formato hh:mm:ss.
eventGridPublishEventTypes Lista de tipos de eventos que se van a publicar en Event Grid. Si no se especifica, se publicarán todos los tipos de evento. Los valores permitidos son Started, Completed, Failed y Terminated.
useAppLease true Si se establece en true, las aplicaciones requerirán que se adquiera una concesión de blob de nivel de aplicación antes de procesar los mensajes de la central de tareas. Para más información, consulte la documentación sobre la recuperación ante desastres y la distribución geográfica. Disponible a partir de la versión 2.3.0.
useLegacyPartitionManagement false Cuando se establece en false, usa un algoritmo de administración de particiones que reduce la posibilidad de que se ejecute la función duplicada al realizar un escalado horizontal. Disponible a partir de la versión 2.3.0.
useTablePartitionManagement false Cuando se establece en true, usa un algoritmo de administración de particiones diseñado para reducir los costos de las cuentas de Azure Storage V2. Disponible a partir de la versión 2.10.0. Esta característica está actualmente en versión preliminar y aún no es compatible con el plan de Consumo.
useGracefulShutdown false (Versión preliminar) Habilite el apagado correcto para reducir la posibilidad de que se produzcan errores de apagado del host en las ejecuciones de función en proceso.
maxEntityOperationBatchSize(2.6.1) Plan de consumo: 50
Plan dedicado/Premium: 5000
Número máximo de operaciones de entidad que se procesan como un lote. Si se establece en 1, el procesamiento por lotes está deshabilitado y cada mensaje de operación se procesa mediante una invocación de función independiente.
storeInputsInOrchestrationHistory false Cuando se establece en true, indica a Durable Task Framework que guarde las entradas de actividad en la tabla de historial. Esto permite mostrar las entradas de función de actividad al consultar el historial de orquestaciones.

Muchos de estos valores son para optimizar el rendimiento. Para obtener más información, vea Rendimiento y escalabilidad.

eventHub

Opciones de configuración para los desencadenadores y enlaces del Centro de eventos.

functions

Lista de las funciones que el host de trabajo ejecuta. Una matriz vacía significa ejecutar todas las funciones. Su uso está previsto solo cuando se ejecuta localmente. En cambio, en las aplicaciones de función de Azure, siga los pasos de Deshabilitamiento de funciones en Azure Functions para deshabilitar funciones específicas en lugar de usar esta configuración.

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

functionTimeout

Indica la duración del tiempo de espera para todas las funciones. En un plan de consumo sin servidor, el intervalo válido es de 1 segundo a 10 minutos, y el valor predeterminado es 5 minutos. En un plan de App Service, no hay ningún límite general y el valor predeterminado es null, lo que indica que no hay tiempo de espera.

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

healthMonitor

Configuración del monitor de estado de host.

{
    "healthMonitor": {
        "enabled": true,
        "healthCheckInterval": "00:00:10",
        "healthCheckWindow": "00:02:00",
        "healthCheckThreshold": 6,
        "counterThreshold": 0.80
    }
}
Propiedad Valor predeterminado Descripción
enabled true Especifica si está habilitada la característica.
healthCheckInterval 10 segundos El intervalo de tiempo entre las comprobaciones periódicas de mantenimiento en segundo plano.
healthCheckWindow 2 minutes Período de tiempo deslizante que se usa con la configuración healthCheckThreshold.
healthCheckThreshold 6 Número máximo de veces que puede producirse un error en la comprobación de mantenimiento antes de que se inicie un reciclaje del host.
counterThreshold 0.80 El umbral en el que un contador de rendimiento se considerará incorrecto.

http

Opciones de configuración para los desencadenadores y enlaces HTTP.

{
    "http": {
        "routePrefix": "api",
        "maxOutstandingRequests": 200,
        "maxConcurrentRequests": 100,
        "dynamicThrottlesEnabled": true
    }
}
Propiedad Valor predeterminado Descripción
dynamicThrottlesEnabled false Cuando se habilita, esta configuración hace que la canalización de procesamiento de la solicitud compruebe periódicamente contadores de rendimiento del sistema como conexiones, subprocesos, procesos, memoria o CPU y, si cualquiera de esos contadores superan un umbral alto integrado (80 %), las solicitudes se rechazan con una respuesta 429 "Ocupado" hasta que los contadores vuelvan a niveles normales.
maxConcurrentRequests sin enlazar (-1) Número máximo de funciones HTTP que se ejecutarán en paralelo. Esto permite controlar la simultaneidad, que a su vez puede ayudar a administrar el uso de recursos. Por ejemplo, podría tener una función HTTP que utiliza una gran cantidad de recursos del sistema (memoria/cpu/sockets) y causa problemas cuando la simultaneidad es demasiado alta. O bien podría tener una función que realiza solicitudes de salida a un servicio de terceros y puede que haya que limitar la velocidad de dichas llamadas. En estos casos puede ayudar aplicar una limitación.
maxOutstandingRequests sin enlazar (-1) Número máximo de solicitudes pendientes que se mantienen en un momento dado. Este límite incluye las solicitudes que están en cola pero no han empezado a ejecutarse y cualquier ejecución en curso. Se rechazan todas las solicitudes entrantes que superen este límite con una respuesta 429 "Too Busy" (demasiado ocupado). Esto permite que los llamadores empleen estrategias de reintento basadas en tiempo y también le ayuda a controlar las latencias de solicitud máximas. Únicamente se controlan los movimientos de la cola que se producen dentro de la ruta de ejecución del host del script. Otras colas, como la cola de solicitudes de ASP.NET, siguen en efecto y no se ven alteradas por esta opción de configuración.
routePrefix api Prefijo de ruta que se aplica a todas las rutas. Use una cadena vacía para quitar el prefijo predeterminado.

id

Identificador único de un host de trabajo. Puede ser un GUID en minúsculas sin guiones. Requerido cuando se realiza la ejecución localmente. Cuando se ejecuta en Azure, se recomienda no establecer un valor de identificador. Cuando id se omite, se genera un identificador automáticamente en Azure.

Si comparte una cuenta de almacenamiento entre varias aplicaciones de función, asegúrese de que cada aplicación de función tiene otro id. Puede omitir la propiedad id o establecer manualmente el id de cada aplicación de función en un valor diferente. El desencadenador de temporizador utiliza un bloqueo de almacenamiento para asegurarse de que solo hay una instancia de temporizador cuando una aplicación de función se escala a varias instancias. Si dos aplicaciones de función comparten el mismo id y cada una usa un desencadenador de temporizador, solo se ejecuta un temporizador.

{
    "id": "9f4ea53c5136457d883d685e57164f08"
}

logger

Controla el filtrado de los registros escritos por un objeto ILogger o context.log.

{
    "logger": {
        "categoryFilter": {
            "defaultLevel": "Information",
            "categoryLevels": {
                "Host": "Error",
                "Function": "Error",
                "Host.Aggregator": "Information"
            }
        }
    }
}
Propiedad Valor predeterminado Descripción
categoryFilter N/D Especifica el filtrado por categoría
defaultLevel Information Para las categorías no especificadas en la matriz categoryLevels, envía registros en este nivel y superiores a Application Insights.
categoryLevels N/D Matriz de categorías que especifica el nivel de registro mínimo para enviar a Application Insights para cada categoría. La categoría especificada aquí controla todas las categorías que comienzan por el mismo valor, y los valores más largos tienen prioridad. En el archivo host.json del ejemplo anterior, todas las categorías que comienzan por "Host.Aggregator" se registran en el nivel Information. Todas las demás categorías que comienzan por "Host", como "Host.Executor", se registran en el nivel Error.

queues

Opciones de configuración para los desencadenadores y enlaces de la cola de Storage.

{
    "queues": {
      "maxPollingInterval": 2000,
      "visibilityTimeout" : "00:00:30",
      "batchSize": 16,
      "maxDequeueCount": 5,
      "newBatchThreshold": 8
    }
}
Propiedad Valor predeterminado Descripción
maxPollingInterval 60000 Intervalo máximo, en milisegundos, entre sondeos de la cola.
visibilityTimeout 0 Intervalo de tiempo entre los reintentos cuando se produce un error al procesar un mensaje.
batchSize 16 El número de mensajes en cola que el runtime de Functions recupera simultáneamente y procesa en paralelo. Cuando el número que se está procesando llega a newBatchThreshold el runtime obtiene otro lote y empieza a procesar esos mensajes. Por lo tanto, el número máximo de mensajes simultáneos que se procesan por función es batchSize más newBatchThreshold. Este límite se aplica por separado a cada función desencadenada por la cola.

Si desea evitar la ejecución en paralelo de los mensajes de una cola, puede establecer batchSize en 1. Sin embargo, este valor solo elimina la simultaneidad siempre y cuando la aplicación de función se ejecute en una única máquina virtual (VM). Si la aplicación de función se escala horizontalmente a varias máquinas virtuales, cada una de ellas podría ejecutar una instancia de cada función desencadenada por la cola.

El valor máximo de batchSize es 32.
maxDequeueCount 5 Número de veces que se intenta procesar un mensaje antes de pasarlo a la cola de mensajes dudosos.
newBatchThreshold batchSize/2 Siempre que el número de mensajes que se procesan simultáneamente llega a este número, el runtime recupera otro lote.

SendGrid

Opción de configuración para el enlace de salida de SendGrind.

{
    "sendGrid": {
        "from": "Contoso Group <admin@contoso.com>"
    }
}    
Propiedad Valor predeterminado Descripción
desde N/D Dirección de correo electrónico del remitente en todas las funciones.

serviceBus

Opción de configuración para los desencadenadores y enlaces de Service Bus.

{ 
    "serviceBus": {
      "maxConcurrentCalls": 16,
      "prefetchCount": 100,
      "autoRenewTimeout": "00:05:00",
      "autoComplete": true
    }
}
Propiedad Valor predeterminado Descripción
maxConcurrentCalls 16 Número máximo de llamadas simultáneas a la devolución de llamada que el bombeo de mensajes debe iniciar. De forma predeterminada, el entorno de ejecución de Functions procesa simultáneamente varios mensajes. Para indicar al entorno de ejecución que procese solo los mensajes de una única cola o tema, establezca maxConcurrentCalls en 1.
prefetchCount N/D Valor predeterminado de PrefetchCount que utilizará el ServiceBusReceiver subyacente.
autoRenewTimeout 00:05:00 Duración máxima dentro de la cual el bloqueo de mensajes se renovará automáticamente.
autoComplete true Cuando es true, el desencadenador completa el procesamiento de mensajes automáticamente cuando la operación se ejecuta correctamente. Cuando sea false, es responsabilidad de la función completar el mensaje antes de volver.

singleton

Opciones de configuración para el comportamiento de bloqueo Singleton. Para más información, consulte problema de compatibilidad de GitHub con singleton.

{
    "singleton": {
      "lockPeriod": "00:00:15",
      "listenerLockPeriod": "00:01:00",
      "listenerLockRecoveryPollingInterval": "00:01:00",
      "lockAcquisitionTimeout": "00:01:00",
      "lockAcquisitionPollingInterval": "00:00:03"
    }
}
Propiedad Valor predeterminado Descripción
lockPeriod 00:00:15 Período durante el cual se producen los bloqueos de nivel de función. Los bloqueos se renuevan automáticamente.
listenerLockPeriod 00:01:00 Período durante el cual se producen los bloqueos de agente de escucha.
listenerLockRecoveryPollingInterval 00:01:00 Intervalo de tiempo que se utiliza para la recuperación de bloqueos del agente de escucha si no se pudo adquirir un bloqueo de agente de escucha durante el inicio.
lockAcquisitionTimeout 00:01:00 Cantidad máxima de tiempo que el entorno en tiempo de ejecución intenta adquirir un bloqueo.
lockAcquisitionPollingInterval N/D Intervalo entre intentos de adquisición de bloqueo.

tracing

Versión 1.x

Opciones de configuración para los registros que se crean mediante un objeto TraceWriter. Para más información, consulte [Registro de C#].

{
    "tracing": {
      "consoleLevel": "verbose",
      "fileLoggingMode": "debugOnly"
    }
}
Propiedad Valor predeterminado Descripción
consoleLevel info Nivel de seguimiento para el registro de la consola. Las opciones son: off, error, warning, info y verbose.
fileLoggingMode debugOnly Nivel de seguimiento para el registro de archivos. Las opciones son never, always, debugOnly.

watchDirectories

Conjunto de directorios de código compartido en los que se deben supervisar los cambios. Garantiza que cuando se cambie el código en estos directorios, las funciones recibirán los cambios.

{
    "watchDirectories": [ "Shared" ]
}

Pasos siguientes