Desencadenador HTTP de Azure Functions

El desencadenador HTTP permite invocar una función con una solicitud HTTP. Puede usar un desencadenador HTTP para crear API sin servidor y responder a webhooks.

El valor devuelto predeterminado para una función desencadenada por HTTP es:

  • HTTP 204 No Content con el cuerpo vacío en Functions 2.x y posterior
  • HTTP 200 OK con el cuerpo vacío en Functions 1.x

Para modificar la respuesta HTTP, configure un enlace de salida.

Para obtener más información sobre los enlaces HTTP, consulte la información general y la referencia sobre enlaces de salida.

Sugerencia

Si planea usar los enlaces HTTP o WebHook, debe evitar el agotamiento de puertos que puede deberse a la creación incorrecta de instancias de HttpClient. Para más información, consulte How to manage connections in Azure Functions (Administración de conexiones en Azure Functions).

Ejemplo

En el ejemplo siguiente se muestra una función de C# que busca un parámetro name en la cadena de consulta o en el cuerpo de la solicitud HTTP. Tenga en cuenta que el valor devuelto se utiliza para el enlace de salida, pero no se requiere un atributo de valor devuelto.

[FunctionName("HttpTriggerCSharp")]
public static async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)]
    HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    string name = req.Query["name"];
    
    string requestBody = String.Empty;
    using (StreamReader streamReader =  new  StreamReader(req.Body))
    {
        requestBody = await streamReader.ReadToEndAsync();
    }
    dynamic data = JsonConvert.DeserializeObject(requestBody);
    name = name ?? data?.name;
    
    return name != null
        ? (ActionResult)new OkObjectResult($"Hello, {name}")
        : new BadRequestObjectResult("Please pass a name on the query string or in the request body");
}

Atributos y anotaciones

En las bibliotecas de clases de C# y en Java, el atributo HttpTrigger está disponible para configurar la función.

Puede establecer el nivel de autorización y los métodos HTTP permitidos en los parámetros del constructor de atributo, así como la plantilla de ruta y el tipo de webhook. Para obtener más información sobre esta configuración, consulte configuración.

En este ejemplo se muestra cómo usar el atributo HttpTrigger.

[FunctionName("HttpTriggerCSharp")]
public static Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequest req)
{
    ...
}

Para obtener un ejemplo completo, vea el ejemplo del desencadenador.

Configuración

En la siguiente tabla se explican las propiedades de configuración de enlace que se definen en el archivo function.json y el atributo HttpTrigger.

Propiedad de function.json Propiedad de atributo Descripción
type N/D Requerida: se debe establecer en httpTrigger.
direction N/D Requerida: se debe establecer en in.
name N/D Requerida: nombre de variable que se usa en el código de la función para la solicitud o el cuerpo de la solicitud.
authLevel AuthLevel Determina qué claves, si las hubiera, deben estar presentes en la solicitud para poder invocar a la función. El nivel de autorización puede ser uno de los siguientes:
  • anonymous: no se requiere ninguna clave de API.
  • function: se requiere una clave de API específica de la función. Este es el valor predeterminado si no se proporciona ninguno.
  • admin: se requiere la clave maestra.
Para más información, consulte la sección sobre las claves de autorización.
methods Métodos Una matriz de los métodos HTTP a los que responde la función. Si no se especifica, la función responde a todos los métodos HTTP. Consulte cómo personalizar el punto de conexión HTTP.
route Route Define la plantilla de ruta y controla las direcciones URL de solicitud a las que responde la función. El valor predeterminado es <functionname> si no se proporciona ninguno. Para más información, consulte cómo personalizar el punto de conexión HTTP.
webHookType WebHookType Compatible solo con la versión 1.x del runtime.

Configura el desencadenador HTTP para que actúe como un receptor de webhook para el proveedor especificado. No establezca la propiedad methods si establece esta propiedad. El tipo de webhook puede ser uno de los valores siguientes:
  • genericJson: un punto de conexión de webhook de uso general sin lógica para un proveedor concreto. Este valor restringe las solicitudes a solo aquellas que usan HTTP POST y con el tipo de contenido application/json.
  • github—La función responde a webhooks de GitHub. No use la propiedad authLevel con webhooks de GitHub. Para más información, consulte la sección sobre webhooks de GitHub que aparece más adelante en este artículo.
  • slack—La función responde a webhooks de Slack. No use la propiedad authLevel con webhooks de Slack. Para más información, consulte la sección sobre webhooks de Slack que aparece más adelante en este artículo.

Carga

El tipo de entrada del desencadenador se declara como HttpRequest o como un tipo personalizado. Si elige HttpRequest, obtiene acceso completo al objeto de solicitud. En un tipo personalizado, el runtime intenta analizar el cuerpo de la solicitud JSON para establecer las propiedades del objeto.

Personalización del punto de conexión HTTP

De forma predeterminada, al crear una función para un desencadenador HTTP, la función se puede dirigir con una ruta que tenga el siguiente formato:

http://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>

Puede personalizar esta ruta mediante el parámetro opcional route del enlace de entrada del desencadenador HTTP. Por ejemplo, el siguiente archivo function.json define una propiedad route para un desencadenador HTTP:

{
    "bindings": [
    {
        "type": "httpTrigger",
        "name": "req",
        "direction": "in",
        "methods": [ "get" ],
        "route": "products/{category:alpha}/{id:int?}"
    },
    {
        "type": "http",
        "name": "res",
        "direction": "out"
    }
    ]
}

Al usar esta configuración, ya se podrá dirigir la función con la ruta de abajo, en lugar de con la original.

http://<APP_NAME>.azurewebsites.net/api/products/electronics/357

Esta configuración permite que el código de la función admita dos parámetros en la dirección: category e id. Para más información sobre cómo se tokenizan los parámetros de ruta en una dirección URL, consulte Enrutamiento en ASP.NET Core.

Puede usar cualquier restricción de ruta de API web con sus parámetros. El siguiente código de función de C# emplea los dos parámetros.

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;

public static IActionResult Run(HttpRequest req, string category, int? id, ILogger log)
{
    var message = String.Format($"Category: {category}, ID: {id}");
    return (ActionResult)new OkObjectResult(message);
}

De forma predeterminada, todas las rutas de la función tienen el prefijo api. También puede personalizar o quitar el prefijo con la propiedad extensions.http.routePrefix del archivo host.json. En el ejemplo siguiente, se quita el prefijo de ruta api utilizando una cadena vacía del prefijo del archivo host.json.

{
    "extensions": {
        "http": {
            "routePrefix": ""
        }
    }
}

Uso de parámetros de ruta

Los parámetros de ruta que definían el patrón route de una función están disponibles para cada enlace. Por ejemplo, si tiene una ruta definida como "route": "products/{id}", un enlace de almacenamiento de tabla puede utilizar el valor del parámetro {id} en la configuración de enlace.

La configuración siguiente muestra cómo se pasa el parámetro {id} al elemento rowKey del enlace.

{
    "type": "table",
    "direction": "in",
    "name": "product",
    "partitionKey": "products",
    "tableName": "products",
    "rowKey": "{id}"
}

Al usar parámetros de ruta, se crea automáticamente una plantilla invoke_URL_template para la función. Los clientes pueden usar la plantilla de dirección URL para comprender los parámetros que deben pasar en la dirección URL al llamar a la función mediante su dirección URL. Vaya a una de las funciones desencadenadas por HTTP en Azure Portal y seleccione Obtener la dirección URL de la función.

Puede tener acceso mediante programación a la plantilla invoke_URL_template con las API de Azure Resource Manager para List Functions (Funciones de lista) o Get Function (Get (función)).

Uso de identidades de cliente

Si la aplicación de función está usando la autenticación/autorización de App Service, puede ver información sobre los clientes autenticados desde el código. Esta información está disponible como encabezados de solicitud insertados por la plataforma.

También puede leer esta información desde los datos de enlace. Esta funcionalidad solo está disponible para el entorno en tiempo de ejecución de Functions en la versión 2.x y posteriores. Actualmente, también está disponible para lenguajes .NET.

La información relacionada con los clientes autenticados está disponible como ClaimsPrincipal. ClaimsPrincipal está disponible como parte del contexto de solicitud, tal como se muestra en el ejemplo siguiente:

using System.Net;
using Microsoft.AspNetCore.Mvc;
using System.Security.Claims;

public static IActionResult Run(HttpRequest req, ILogger log)
{
    ClaimsPrincipal identities = req.HttpContext.User;
    // ...
    return new OkObjectResult();
}

Como alternativa, ClaimsPrincipal se puede incluir como un parámetro adicional en la firma de función:

using System.Net;
using Microsoft.AspNetCore.Mvc;
using System.Security.Claims;
using Newtonsoft.Json.Linq;

public static void Run(JObject input, ClaimsPrincipal principal, ILogger log)
{
    // ...
    return;
}

Claves de acceso de función

Functions permite usar claves para dificultar el acceso a los puntos de conexión de función HTTP durante el desarrollo. A menos que el nivel de acceso HTTP en una función desencadenada por HTTP se establezca en anonymous, las solicitudes deben incluir una clave de acceso de API.

Aunque las claves proporcionan un mecanismo de seguridad predeterminado, podría plantearse la posibilidad de opciones adicionales para proteger un punto de conexión HTTP en producción. Por ejemplo, por lo general, no es recomendable distribuir un secreto compartido en las aplicaciones públicas. Si se llama a la función desde un cliente público, puede que sea conveniente implementar otro mecanismo de seguridad. Para obtener más información, vea Proteger un punto de conexión HTTP en producción.

Al renovar los valores de la clave de función, debe redistribuir manualmente los valores de clave actualizados a todos los clientes que llaman a la función.

Ámbitos de autorización (nivel de función)

Hay dos ámbitos de acceso para las claves de nivel de función:

  • Función: estas claves se aplican solo a las funciones específicas en las que se definen. Cuando se usan como una clave de API, solo permiten el acceso a esa función.

  • Host: las claves con un ámbito de host se pueden usar para acceder a todas las funciones dentro de la aplicación de función. Cuando se usan como una clave de API, permiten el acceso a cualquier función dentro de la aplicación de función.

Para cada clave se usa un nombre fácilmente referenciable y hay una clave predeterminada (denominada "predeterminada") en el nivel de función y host. Las claves de función tienen prioridad sobre las claves de host. Si se definen dos claves con el mismo nombre, siempre se usa la clave de función.

Clave maestra (nivel de administrador)

Cada aplicación de función también tiene una clave de host de nivel de administrador denominada _master. Además de proporcionar acceso de nivel de host a todas las funciones de la aplicación, la clave maestra también proporciona acceso administrativo a las API REST del entorno de ejecución. No se puede revocar esta clave. Al establecer un nivel de acceso admin, las solicitudes deben usar la clave maestra; cualquier otra clave da lugar a un error de acceso.

Precaución

Debido a los permisos elevados de la aplicación de función otorgados por la clave maestra, no debe compartir esta clave con terceros ni distribuirla en aplicaciones cliente nativas. Tenga cuidado al elegir el nivel de acceso de administrador.

Obtención de claves

Las claves se almacenan como parte de la aplicación de función en Azure y se cifran en reposo. Para ver las claves, crear nuevas o asignarles nuevos valores, vaya a una de las funciones desencadenadas por HTTP de Azure Portal y seleccione Claves de función.

También puede administrar claves de host. Vaya a la aplicación de funciones de Azure Portal y seleccione Claves de la aplicación.

Puede obtener claves de función y de host mediante programación con las API de Azure Resource Manager. Hay API para List Function Keys (Enumerar claves de función) y List Host Keys (Enumerar claves de host) y, al usar ranuras de implementación, las API equivalentes son List Function Keys Slot (Enumerar ranura de claves de función) y List Host Keys Slot (Enumerar ranura de claves de host).

También puede crear nuevas claves de función y de host mediante programación con las API Create Or Update Function Secret (Crear o actualizar secreto de función) , Create Or Update Function Secret Slot (Crear o actualizar ranura de secreto de función), Create Or Update Host Secret (Crear o actualizar secreto de host) y Create Or Update Host Secret Slot (Crear o actualizar ranura de secreto de host).

Las claves de función y de host se pueden eliminar mediante programación con las API Delete Function Secret (Eliminar secreto de función), Delete Function Secret Slot (Eliminar ranura de secreto de función), Delete Host Secret (Eliminar secreto de host) y Delete Host Secret Slot (Eliminar ranura de secreto de host).

También puede usar las API de administración de claves heredadas para obtener claves de función, pero, en su lugar, se recomienda usar las API de Azure Resource Manager.

Autorización de la clave de API

La mayoría de las plantillas de desencadenador HTTP requieren una clave de API en la solicitud. Por lo tanto, la solicitud HTTP normalmente se parece a la siguiente dirección URL:

https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?code=<API_KEY>

La clave se puede incluir en una variable de cadena de consulta denominada code, como arriba. También puede incluirse en un encabezado HTTP x-functions-key. El valor de la clave puede ser cualquier clave de función definida para la función o cualquier clave de host.

Puede permitir solicitudes anónimas, que no requieren claves. También puede exigir que se use la clave maestra. Cambie el nivel de autorización predeterminado mediante la propiedad authLevel en el JSON de enlace. Para más información, consulte Desencadenador: configuración.

Nota

Cuando las funciones se ejecutan localmente, la autorización se deshabilita independientemente del valor del nivel de autorización especificado. Después de publicar en Azure, se aplica el valor authLevel del desencadenador. Las claves siguen siendo necesarias cuando se ejecutan localmente en un contenedor.

Proteger un punto de conexión HTTP en producción

Para proteger totalmente los puntos de conexión de función en producción, considere la posibilidad de implementar una de las opciones de seguridad siguientes de nivel de aplicación de función. Cuando use alguno de estos métodos de seguridad de nivel de aplicación de función, debe establecer el nivel de autorización de función desencadenado por HTTP en anonymous.

Habilitación de la autenticación o la autorización de App Service

La plataforma App Service le permite usar Azure Active Directory (AAD) y varios proveedores de identidades de terceros para autenticar a los clientes. Se puede usar esta estrategia para implementar reglas de autorización personalizadas para las funciones y permite trabajar con información de usuario desde el código de función. Para obtener más información, vea Autenticación y autorización en Azure App Service y Uso de identidades de cliente.

Uso de Azure API Management (APIM) para autenticar solicitudes

APIM proporciona una serie de opciones de seguridad de API para las solicitudes entrantes. Para obtener más información, vea Directivas de autenticación de Azure API Management. Con APIM, puede configurar la aplicación de función de modo que solo acepte solicitudes de la dirección IP de la instancia de APIM. Para obtener más información, vea Restricciones de las direcciones IP.

Implementación de la aplicación de funciones en aislamiento

Azure App Service Environment (ASE) proporciona un entorno de hospedaje dedicado en el que ejecutar las funciones. ASE le permite configurar una puerta de enlace de front-end única que se puede usar para autenticar todas las solicitudes entrantes. Para obtener más información, vea Configuración de un firewall de aplicaciones web (WAF) para entornos de App Service.

webhooks

Nota

El modo de webhook solo está disponible para la versión 1.x del runtime de Functions. Este cambio se realizó para mejorar el rendimiento de los desencadenadores HTTP en la versión 2.x y posteriores.

En la versión 1.x, las plantillas de webhook proporcionan una validación adicional para las cargas de webhook. En la versión 2.x y posteriores, el desencadenador HTTP base todavía funciona y es el modo recomendado para webhooks.

Webhooks de GitHub

Para responder a webhooks de GitHub, primero cree la función con un desencadenador HTTP y establezca la propiedad webHookType en github. Luego copie su dirección URL y clave de API en la página Agregar webhook del repositorio GitHub.

Captura de pantalla que muestra cómo agregar un webhook para la función.

Webhooks de Slack

El webhook de Slack genera un token en lugar de permitirle especificarlo, por lo que debe configurar una clave específica de función con el token desde Slack. Consulte Claves de autorización.

Webhooks y claves

La autorización de webhook se controla mediante el componente receptor de webhook, parte del desencadenador HTTP; el mecanismo varía según el tipo de webhook. Cada mecanismo se basa en una clave. De forma predeterminada, se usa la clave de función denominada "default". Para usar otra clave, configure el proveedor de webhook de modo que envíe el nombre de la clave con la solicitud de una de las siguientes maneras:

  • Cadena de consulta: el proveedor pasa el nombre de la clave en el parámetro de la cadena de consulta clientid, como https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?clientid=<KEY_NAME>.
  • Encabezado de solicitud: el proveedor pasa el nombre de clave en el encabezado x-functions-clientid.

Tipos de contenido

Para pasar datos binarios y de formulario a una función que no es de C#, es necesario utilizar el encabezado Content-Type adecuado. Los tipos de contenido admitidos incluyen octet-stream para los datos binarios y tipos de varias partes.

Problemas conocidos

En las funciones que no son de C#, las solicitudes enviadas con el tipo de contenido image/jpeg producen un valor string pasado a la función. En casos como estos, puede convertir manualmente el valor string en una matriz de bytes para acceder a los datos binarios sin formato.

Límites

La longitud de la solicitud HTTP está limitada a 100 MB (104 857 600 bytes) y la longitud de la dirección URL a 4 KB (4 096 bytes). El elemento httpRuntime del archivo Web.config especifica estos límites.

Si una función que usa el desencadenador HTTP no se completa en menos de 230 segundos, Azure Load Balancer agotará el tiempo de espera y devolverá un error HTTP 502. La función seguirá ejecutándose, pero no podrá devolver una respuesta HTTP. En el caso de funciones de ejecución prolongada, se recomienda que siga patrones asincrónicos y que devuelva una ubicación donde pueda hacer ping con el estado de la solicitud. Para más información sobre cuánto tiempo se puede ejecutar una función, consulte Escalado y hospedaje: Plan de consumo.

Pasos siguientes