Enlaces y desencadenadores HTTP de Azure FunctionsAzure Functions HTTP triggers and bindings

En este artículo se explica cómo trabajar con desencadenadores y enlaces de salida HTTP en Azure Functions.This article explains how to work with HTTP triggers and output bindings in Azure Functions.

Es posible personalizar un desencadenador HTTP para responder a webhooks.An HTTP trigger can be customized to respond to webhooks.

Esta es la información de referencia para desarrolladores de Azure Functions.This is reference information for Azure Functions developers. Si está familiarizado con Azure Functions, comience con los siguientes recursos:If you're new to Azure Functions, start with the following resources:

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.If you plan to use the HTTP or WebHook bindings, plan to avoid port exhaustion that can be caused by improper instantiation of HttpClient. Para más información, consulte How to manage connections in Azure Functions (Administración de conexiones en Azure Functions).For more information, see How to manage connections in Azure Functions.

El código en este artículo toma como valor predeterminado la sintaxis de Functions 2.x, que usa .NET Core.The code in this article defaults to Functions 2.x syntax which uses .NET Core. Para obtener información sobre la sintaxis de 1.x, consulte las plantillas de Functions 1.x.For information on the 1.x syntax, see the 1.x functions templates.

Paquetes: Functions 1.xPackages - Functions 1.x

Los enlaces HTTP se proporcionan en el paquete NuGet Microsoft.Azure.WebJobs.Extensions.Http, versión 1.x.The HTTP bindings are provided in the Microsoft.Azure.WebJobs.Extensions.Http NuGet package, version 1.x. El código fuente del paquete está en el repositorio azure-webjobs-sdk-extensions de GitHub.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

En todos los entornos de desarrollo, se proporciona automáticamente compatibilidad para este enlace.Support for this binding is automatically provided in all development environments. No tiene que instalar el paquete manualmente ni que registrar la extensión.You don't have to manually install the package or register the extension.

Paquetes: Functions 2.xPackages - Functions 2.x

Los enlaces HTTP se proporcionan en el paquete NuGet Microsoft.Azure.WebJobs.Extensions.Http, versión 3.x.The HTTP bindings are provided in the Microsoft.Azure.WebJobs.Extensions.Http NuGet package, version 3.x. El código fuente del paquete está en el repositorio azure-webjobs-sdk-extensions de GitHub.Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

En todos los entornos de desarrollo, se proporciona automáticamente compatibilidad para este enlace.Support for this binding is automatically provided in all development environments. No tiene que instalar el paquete manualmente ni que registrar la extensión.You don't have to manually install the package or register the extension.

DesencadenadorTrigger

El desencadenador HTTP permite invocar una función con una solicitud HTTP.The HTTP trigger lets you invoke a function with an HTTP request. Puede usar un desencadenador HTTP para crear API sin servidor y responder a webhooks.You can use an HTTP trigger to build serverless APIs and respond to webhooks.

De forma predeterminada, un desencadenador HTTP devuelve HTTP 200 OK con un cuerpo vacío en Functions 1.x, o HTTP 204 No Content con un cuerpo vacío en Functions 2.x.By default, an HTTP trigger returns HTTP 200 OK with an empty body in Functions 1.x, or HTTP 204 No Content with an empty body in Functions 2.x. Para modificar la respuesta, configure un enlace de salida HTTP.To modify the response, configure an HTTP output binding.

Desencadenador: ejemploTrigger - example

Vea el ejemplo específico del lenguaje:See the language-specific example:

Desencadenador: ejemplo de C#Trigger - C# example

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.The following example shows a C# function that looks for a name parameter either in the query string or the body of the HTTP request. Tenga en cuenta que el valor devuelto se utiliza para el enlace de salida, pero no se requiere un atributo de valor devuelto.Notice that the return value is used for the output binding, but a return value attribute isn't required.

[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 = await new StreamReader(req.Body).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");
}

Desencadenador: ejemplo de script de C#Trigger - C# script example

En el ejemplo siguiente se muestra un enlace de desencadenador en un archivo function.json y una función de script de C# que usa el enlace.The following example shows a trigger binding in a function.json file and a C# script function that uses the binding. La función busca un parámetro name en la cadena de consulta o en el cuerpo de la solicitud HTTP.The function looks for a name parameter either in the query string or the body of the HTTP request.

Este es el archivo function.json:Here's the function.json file:

{
    "disabled": false,
    "bindings": [
        {
            "authLevel": "function",
            "name": "req",
            "type": "httpTrigger",
            "direction": "in",
            "methods": [
                "get",
                "post"
            ]
        },
        {
            "name": "$return",
            "type": "http",
            "direction": "out"
        }
    ]
}

En la sección de configuración se explican estas propiedades.The configuration section explains these properties.

Este es el código de script de C# que se enlaza a HttpRequest:Here's C# script code that binds to HttpRequest:

#r "Newtonsoft.Json"

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

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    string name = req.Query["name"];

    string requestBody = await new StreamReader(req.Body).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");
}

Puede enlazar a un objeto personalizado en lugar de HttpRequest.You can bind to a custom object instead of HttpRequest. Este objeto se crea a partir del cuerpo de la solicitud y se analiza como JSON.This object is created from the body of the request and parsed as JSON. Del mismo modo, puede pasarse un tipo al enlace de la salida de respuesta HTTP y se devuelve como el cuerpo de la respuesta, con el código de estado 200.Similarly, a type can be passed to the HTTP response output binding and returned as the response body, along with a 200 status code.

using System.Net;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

public static string Run(Person person, ILogger log)
{   
    return person.Name != null
        ? (ActionResult)new OkObjectResult($"Hello, {person.Name}")
        : new BadRequestObjectResult("Please pass an instance of Person.");
}

public class Person {
     public string Name {get; set;}
}

Desencadenador: ejemplo de F#Trigger - F# example

En el ejemplo siguiente se muestra un enlace de desencadenador en un archivo function.json y una función de F# que usa el enlace.The following example shows a trigger binding in a function.json file and an F# function that uses the binding. La función busca un parámetro name en la cadena de consulta o en el cuerpo de la solicitud HTTP.The function looks for a name parameter either in the query string or the body of the HTTP request.

Este es el archivo function.json:Here's the function.json file:

{
  "bindings": [
    {
      "authLevel": "function",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in"
    },
    {
      "name": "res",
      "type": "http",
      "direction": "out"
    }
  ],
  "disabled": false
}

En la sección de configuración se explican estas propiedades.The configuration section explains these properties.

Este es el código de F#:Here's the F# code:

open System.Net
open System.Net.Http
open FSharp.Interop.Dynamic

let Run(req: HttpRequestMessage) =
    async {
        let q =
            req.GetQueryNameValuePairs()
                |> Seq.tryFind (fun kv -> kv.Key = "name")
        match q with
        | Some kv ->
            return req.CreateResponse(HttpStatusCode.OK, "Hello " + kv.Value)
        | None ->
            let! data = Async.AwaitTask(req.Content.ReadAsAsync<obj>())
            try
                return req.CreateResponse(HttpStatusCode.OK, "Hello " + data?name)
            with e ->
                return req.CreateErrorResponse(HttpStatusCode.BadRequest, "Please pass a name on the query string or in the request body")
    } |> Async.StartAsTask

Necesita un archivo project.json que use NuGet para hacer referencia a los ensamblados FSharp.Interop.Dynamic y Dynamitey, como se muestra en el ejemplo siguiente:You need a project.json file that uses NuGet to reference the FSharp.Interop.Dynamic and Dynamitey assemblies, as shown in the following example:

{
  "frameworks": {
    "net46": {
      "dependencies": {
        "Dynamitey": "1.0.2",
        "FSharp.Interop.Dynamic": "3.0.0"
      }
    }
  }
}

Desencadenador: ejemplo de JavaScriptTrigger - JavaScript example

En el ejemplo siguiente se muestra un enlace de desencadenador en un archivo function.json y una función de JavaScript que usa el enlace.The following example shows a trigger binding in a function.json file and a JavaScript function that uses the binding. La función busca un parámetro name en la cadena de consulta o en el cuerpo de la solicitud HTTP.The function looks for a name parameter either in the query string or the body of the HTTP request.

Este es el archivo function.json:Here's the function.json file:

{
    "disabled": false,    
    "bindings": [
        {
            "authLevel": "function",
            "type": "httpTrigger",
            "direction": "in",
            "name": "req"
        },
        {
            "type": "http",
            "direction": "out",
            "name": "res"
        }
    ]
}

En la sección de configuración se explican estas propiedades.The configuration section explains these properties.

Este es el código de JavaScript:Here's the JavaScript code:

module.exports = function(context, req) {
    context.log('Node.js HTTP trigger function processed a request. RequestUri=%s', req.originalUrl);

    if (req.query.name || (req.body && req.body.name)) {
        context.res = {
            // status defaults to 200 */
            body: "Hello " + (req.query.name || req.body.name)
        };
    }
    else {
        context.res = {
            status: 400,
            body: "Please pass a name on the query string or in the request body"
        };
    }
    context.done();
};

Ejemplo de desencadenador de PythonTrigger - Python example

En el ejemplo siguiente se muestra un enlace de desencadenador en un archivo function.json y una función de Python que usa el enlace.The following example shows a trigger binding in a function.json file and a Python function that uses the binding. La función busca un parámetro name en la cadena de consulta o en el cuerpo de la solicitud HTTP.The function looks for a name parameter either in the query string or the body of the HTTP request.

Este es el archivo function.json:Here's the function.json file:

{
    "scriptFile": "__init__.py",
    "disabled": false,    
    "bindings": [
        {
            "authLevel": "function",
            "type": "httpTrigger",
            "direction": "in",
            "name": "req"
        },
        {
            "type": "http",
            "direction": "out",
            "name": "res"
        }
    ]
}

En la sección de configuración se explican estas propiedades.The configuration section explains these properties.

Este es el código de Python:Here's the Python code:

import logging
import azure.functions as func


def main(req: func.HttpRequest) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request.')

    name = req.params.get('name')
    if not name:
        try:
            req_body = req.get_json()
        except ValueError:
            pass
        else:
            name = req_body.get('name')

    if name:
        return func.HttpResponse(f"Hello {name}!")
    else:
        return func.HttpResponse(
            "Please pass a name on the query string or in the request body",
            status_code=400
        )

Desencadenador: ejemplos de JavaTrigger - Java examples

En el ejemplo siguiente se muestra un enlace de desencadenador HTTP de un archivo function.json y las funciones de Java correspondientes que usan el enlace.The following examples show the HTTP trigger binding in a function.json file and the respective Java functions that use the binding.

Este es el archivo function.json:Here's the function.json file:

{
    "disabled": false,    
    "bindings": [
        {
            "authLevel": "anonymous",
            "type": "httpTrigger",
            "direction": "in",
            "name": "req"
        },
        {
            "type": "http",
            "direction": "out",
            "name": "res"
        }
    ]
}

Leer el parámetro de la cadena de consulta (Java)Read parameter from the query string (Java)

En este ejemplo se lee un parámetro, denominado id, desde la cadena de consulta, y se usa para generar un documento JSON devuelto al cliente, con el tipo de contenido application/json.This example reads a parameter, named id, from the query string, and uses it to build a JSON document returned to the client, with content type application/json.

    @FunctionName("TriggerStringGet")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", 
              methods = {HttpMethod.GET}, 
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {
        
        // Item list
        context.getLogger().info("GET parameters are: " + request.getQueryParameters());

        // Get named parameter
        String id = request.getQueryParameters().getOrDefault("id", "");

        // Convert and display
        if (id.isEmpty()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        } 
        else {
            // return JSON from to the client
            // Generate document
            final String name = "fake_name";
            final String jsonDocument = "{\"id\":\"" + id + "\", " + 
                                         "\"description\": \"" + name + "\"}";
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(jsonDocument)
                          .build();
        }
    }

Leer el cuerpo de una solicitud POST (Java)Read body from a POST request (Java)

En este ejemplo se lee el cuerpo de una solicitud POST, como String, y se usa para generar un documento JSON devuelto al cliente, con el tipo de contenido application/json.This example reads the body of a POST request, as a String, and uses it to build a JSON document returned to the client, with content type application/json.

    @FunctionName("TriggerStringPost")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", 
              methods = {HttpMethod.POST}, 
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {
        
        // Item list
        context.getLogger().info("Request body is: " + request.getBody().orElse(""));

        // Check request body
        if (!request.getBody().isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        } 
        else {
            // return JSON from to the client
            // Generate document
            final String body = request.getBody().get();
            final String jsonDocument = "{\"id\":\"123456\", " + 
                                         "\"description\": \"" + body + "\"}";
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(jsonDocument)
                          .build();
        }
    }

Leer el parámetro de una ruta (Java)Read parameter from a route (Java)

En este ejemplo se lee un parámetro obligatorio, denominado id, y un parámetro opcional name de la ruta de acceso, y se usa para generar un documento JSON devuelto al cliente, con el tipo de contenido application/json.This example reads a mandatory parameter, named id, and an optional parameter name from the route path, and uses them to build a JSON document returned to the client, with content type application/json. TT

    @FunctionName("TriggerStringRoute")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", 
              methods = {HttpMethod.GET}, 
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "trigger/{id}/{name=EMPTY}") // name is optional and defaults to EMPTY
            HttpRequestMessage<Optional<String>> request,
            @BindingName("id") String id,
            @BindingName("name") String name,
            final ExecutionContext context) {
        
        // Item list
        context.getLogger().info("Route parameters are: " + id);

        // Convert and display
        if (id == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        } 
        else {
            // return JSON from to the client
            // Generate document
            final String jsonDocument = "{\"id\":\"" + id + "\", " + 
                                         "\"description\": \"" + name + "\"}";
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(jsonDocument)
                          .build();
        }
    }

Leer el cuerpo POJO de una solicitud POST (Java)Read POJO body from a POST request (Java)

Este es el código para la clase ToDoItem, a la que se hace referencia en este ejemplo:Here is the code for the ToDoItem class, referenced in this example:


public class ToDoItem {

  private String id;
  private String description;  

  public ToDoItem(String id, String description) {
    this.id = id;
    this.description = description;
  }

  public String getId() {
    return id;
  }

  public String getDescription() {
    return description;
  }
  
  @Override
  public String toString() {
    return "ToDoItem={id=" + id + ",description=" + description + "}";
  }
}

En este ejemplo se lee el cuerpo de una solicitud POST.This example reads the body of a POST request. El cuerpo de la solicitud se deserializa automáticamente en un objeto ToDoItem y se devuelve al cliente, con el tipo de contenido application/json.The request body gets automatically de-serialized into a ToDoItem object, and is returned to the client, with content type application/json. El parámetro ToDoItem se serializa en runtime de Functions, ya que está asignado a la propiedad body de la clase HttpMessageResponse.Builder.The ToDoItem parameter is serialized by the Functions runtime as it is assigned to the body property of the HttpMessageResponse.Builder class.

    @FunctionName("TriggerPojoPost")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", 
              methods = {HttpMethod.POST}, 
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<ToDoItem>> request,
            final ExecutionContext context) {
        
        // Item list
        context.getLogger().info("Request body is: " + request.getBody().orElse(null));

        // Check request body
        if (!request.getBody().isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        } 
        else {
            // return JSON from to the client
            // Generate document
            final ToDoItem body = request.getBody().get();
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(body)
                          .build();
        }
    }

Desencadenador: atributosTrigger - attributes

En las bibliotecas de clases de C#, use el atributo HttpTrigger.In C# class libraries, use the HttpTrigger attribute.

Puede establecer el nivel de autorización y los métodos HTTP permitidos en los parámetros del constructor de atributo. Además, existen propiedades para la plantilla de ruta y el tipo de webhook.You can set the authorization level and allowable HTTP methods in attribute constructor parameters, and there are properties for webhook type and route template. Para más información sobre estos valores, consulte Desencadenador: configuración.For more information about these settings, see Trigger - configuration. A continuación, se muestra un atributo HttpTrigger en una signatura de método:Here's an HttpTrigger attribute in a method signature:

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

Para un ejemplo completo, consulte Desencadenador: ejemplo de C#.For a complete example, see Trigger - C# example.

Desencadenador: configuraciónTrigger - configuration

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.The following table explains the binding configuration properties that you set in the function.json file and the HttpTrigger attribute.

Propiedad de function.jsonfunction.json property Propiedad de atributoAttribute property DESCRIPCIÓNDescription
typetype N/Dn/a Requerida: se debe establecer en httpTrigger.Required - must be set to httpTrigger.
directiondirection N/Dn/a Requerida: se debe establecer en in.Required - must be set to in.
namename N/Dn/a Requerida: nombre de variable que se usa en el código de la función para la solicitud o el cuerpo de la solicitud.Required - the variable name used in function code for the request or request body.
authLevelauthLevel AuthLevelAuthLevel Determina qué claves, si las hubiera, deben estar presentes en la solicitud para poder invocar a la función.Determines what keys, if any, need to be present on the request in order to invoke the function. El nivel de autorización puede ser uno de los siguientes:The authorization level can be one of the following values:
  • anonymous: no se requiere ninguna clave de API.anonymous—No API key is required.
  • function: se requiere una clave de API específica de la función.function—A function-specific API key is required. Este es el valor predeterminado si no se proporciona ninguno.This is the default value if none is provided.
  • admin: se requiere la clave maestra.admin—The master key is required.
Para más información, consulte la sección sobre las claves de autorización.For more information, see the section about authorization keys.
methodsmethods MétodosMethods Una matriz de los métodos HTTP a los que responde la función.An array of the HTTP methods to which the function responds. Si no se especifica, la función responde a todos los métodos HTTP.If not specified, the function responds to all HTTP methods. Consulte cómo personalizar el punto de conexión HTTP.See customize the http endpoint.
routeroute RouteRoute Define la plantilla de ruta y controla las direcciones URL de solicitud a las que responde la función.Defines the route template, controlling to which request URLs your function responds. El valor predeterminado es <functionname> si no se proporciona ninguno.The default value if none is provided is <functionname>. Para más información, consulte cómo personalizar el punto de conexión HTTP.For more information, see customize the http endpoint.
webHookTypewebHookType WebHookTypeWebHookType Compatible solo con la versión 1.x del runtime.Supported only for the version 1.x runtime.

Configura el desencadenador HTTP para que actúe como un receptor de webhook para el proveedor especificado.Configures the HTTP trigger to act as a webhook receiver for the specified provider. No establezca la propiedad methods si establece esta propiedad.Don't set the methods property if you set this property. El tipo de webhook puede ser uno de los valores siguientes:The webhook type can be one of the following values:
  • genericJson: un punto de conexión de webhook de uso general sin lógica para un proveedor concreto.genericJson—A general-purpose webhook endpoint without logic for a specific provider. Este valor restringe las solicitudes a solo aquellas que usan HTTP POST y con el tipo de contenido application/json.This setting restricts requests to only those using HTTP POST and with the application/json content type.
  • github—La función responde a webhooks de GitHub.github—The function responds to GitHub webhooks. No use la propiedad authLevel con webhooks de GitHub.Do not use the authLevel property with GitHub webhooks. Para más información, consulte la sección sobre webhooks de GitHub que aparece más adelante en este artículo.For more information, see the GitHub webhooks section later in this article.
  • slack—La función responde a webhooks de Slack.slack—The function responds to Slack webhooks. No use la propiedad authLevel con webhooks de Slack.Do not use the authLevel property with Slack webhooks. Para más información, consulte la sección sobre webhooks de Slack que aparece más adelante en este artículo.For more information, see the Slack webhooks section later in this article.

Desencadenador: usoTrigger - usage

Para las funciones C# y F #, puede declarar que el tipo de entrada del desencadenador sea HttpRequest o un tipo personalizado.For C# and F# functions, you can declare the type of your trigger input to be either HttpRequest or a custom type. Si elige HttpRequest, obtiene acceso completo al objeto de solicitud.If you choose HttpRequest, you get full access to the request object. En un tipo personalizado, el runtime intenta analizar el cuerpo de la solicitud JSON para establecer las propiedades del objeto.For a custom type, the runtime tries to parse the JSON request body to set the object properties.

Para las funciones de JavaScript, el sistema en tiempo de ejecución de Funciones proporciona el cuerpo de la solicitud en lugar del objeto de solicitud.For JavaScript functions, the Functions runtime provides the request body instead of the request object. Para más información, consulte el ejemplo de desencadenador de JavaScript.For more information, see the JavaScript trigger example.

Personalización del punto de conexión HTTPCustomize the HTTP endpoint

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:By default when you create a function for an HTTP trigger, the function is addressable with a route of the form:

http://<yourapp>.azurewebsites.net/api/<funcname>

Puede personalizar esta ruta mediante el parámetro opcional route del enlace de entrada del desencadenador HTTP.You can customize this route using the optional route property on the HTTP trigger's input binding. Por ejemplo, el siguiente archivo function.json define una propiedad route para un desencadenador HTTP:As an example, the following function.json file defines a route property for an HTTP trigger:

{
    "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.Using this configuration, the function is now addressable with the following route instead of the original route.

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

Esto permite que el código de la función admita dos parámetros en la dirección: category e id. Puede usar cualquier restricción de ruta de API web con sus parámetros.This allows the function code to support two parameters in the address, category and id. You can use any Web API Route Constraint with your parameters. El siguiente código de función de C# emplea los dos parámetros.The following C# function code makes use of both parameters.

public static Task<IActionResult> Run(HttpRequest req, string category, int? id, ILogger log)
{
    if (id == null)
    {
        return (ActionResult)new OkObjectResult($"All {category} items were requested.");
    }
    else
    {
        return (ActionResult)new OkObjectResult($"{category} item with id = {id} has been requested.");
    }
    
    // -----
    log.LogInformation($"C# HTTP trigger function processed a request. RequestUri={req.RequestUri}");
}

A continuación, encontrará el código de función de Node.js que usa los mismos parámetros de ruta.Here is Node.js function code that uses the same route parameters.

module.exports = function (context, req) {

    var category = context.bindingData.category;
    var id = context.bindingData.id;

    if (!id) {
        context.res = {
            // status defaults to 200 */
            body: "All " + category + " items were requested."
        };
    }
    else {
        context.res = {
            // status defaults to 200 */
            body: category + " item with id = " + id + " was requested."
        };
    }

    context.done();
}

De forma predeterminada, todas las rutas de la función tienen el prefijo api.By default, all function routes are prefixed with api. También puede personalizar o quitar el prefijo con la propiedad http.routePrefix del archivo host.json.You can also customize or remove the prefix using the http.routePrefix property in your host.json file. En el ejemplo siguiente, se quita el prefijo de ruta api utilizando una cadena vacía del prefijo del archivo host.json.The following example removes the api route prefix by using an empty string for the prefix in the host.json file.

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

Uso de identidades de clienteWorking with client identities

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.If your function app is using App Service Authentication / Authorization, you can view information about authenticated clients from your code. Esta información está disponible como encabezados de solicitud insertados por la plataforma.This information is available as request headers injected by the platform.

También puede leer esta información desde los datos de enlace.You can also read this information from binding data. Esta funcionalidad solo está disponible para el entorno de ejecución de Functions 2.x.This capability is only available to the Functions 2.x runtime. Actualmente, también está disponible para lenguajes .NET.It is also currently only available for .NET languages.

En lenguajes .NET, esta información está disponible como ClaimsPrincipal.In .NET languages, this information is available as a ClaimsPrincipal. ClaimsPrincipal está disponible como parte del contexto de solicitud, tal como se muestra en el ejemplo siguiente:The ClaimsPrincipal is available as part of the request context as shown in the following example:

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:Alternatively, the ClaimsPrincipal can simply be included as an additional parameter in the function signature:

#r "Newtonsoft.Json"

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 autorizaciónAuthorization keys

Functions permite usar claves para dificultar el acceso a los puntos de conexión de función HTTP durante el desarrollo.Functions lets you use keys to make it harder to access your HTTP function endpoints during development. Un desencadenador HTTP estándar puede necesitar que haya una clave de API de este tipo en la solicitud.A standard HTTP trigger may require such an API key be present in the request.

Importante

Aunque las claves pueden ayudar a ofuscar los puntos de conexión HTTP durante el desarrollo, no están diseñadas como una manera de proteger un desencadenador HTTP en producción.While keys may help obfuscate your HTTP endpoints during development, they are not intended as a way to secure an HTTP trigger in production. Para obtener más información, vea Proteger un punto de conexión HTTP en producción.To learn more, see Secure an HTTP endpoint in production.

Nota

En el runtime 1.x de Functions, los proveedores de webhooks pueden usar claves para autorizar solicitudes de varias maneras, según lo que admita el proveedor.In the Functions 1.x runtime, webhook providers may use keys to authorize requests in a variety of ways, depending on what the provider supports. Esto se trata en Webhooks y claves.This is covered in Webhooks and keys. La versión 2.x del runtime no incluye compatibilidad integrada con proveedores de webhooks.The version 2.x runtime does not include built-in support for webhook providers.

Existen dos tipos de claves:There are two types of keys:

  • Claves de host: estas claves se comparten entre todas las funciones dentro de la aplicación de función.Host keys: These keys are shared by all functions within the function app. Cuando se usan como una clave de API, permiten el acceso a cualquier función dentro de la aplicación de función.When used as an API key, these allow access to any function within the function app.
  • Claves de función: estas claves se aplican solo a las funciones específicas en las que se definen.Function keys: These keys apply only to the specific functions under which they are defined. Cuando se usan como una clave de API, solo permiten el acceso a esa función.When used as an API key, these only allow access to that function.

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.Each key is named for reference, and there is a default key (named "default") at the function and host level. Las claves de función tienen prioridad sobre las claves de host.Function keys take precedence over host keys. Si se definen dos claves con el mismo nombre, siempre se usa la clave de función.When two keys are defined with the same name, the function key is always used.

Cada aplicación de función además tiene una clave maestra especial.Each function app also has a special master key. Esta clave es una clave de host denominada _master, que proporciona acceso administrativo a las API en tiempo de ejecución.This key is a host key named _master, which provides administrative access to the runtime APIs. No se puede revocar esta clave.This key cannot be revoked. Al establecer un nivel de autorización admin, las solicitudes deben usar la clave maestra; cualquier otra clave da lugar a un error de autorización.When you set an authorization level of admin, requests must use the master key; any other key results in authorization failure.

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.Due to the elevated permissions in your function app granted by the master key, you should not share this key with third parties or distribute it in native client applications. Tenga cuidado al elegir el nivel de autorización de administrador.Use caution when choosing the admin authorization level.

Obtención de clavesObtaining keys

Las claves se almacenan como parte de la aplicación de función en Azure y se cifran en reposo.Keys are stored as part of your function app in Azure and are encrypted at rest. Para ver las claves, crear nuevas o asignarles nuevos valores, vaya a una de las funciones desencadenadas por HTTP de Azure Portal y seleccione Administrar.To view your keys, create new ones, or roll keys to new values, navigate to one of your HTTP-triggered functions in the Azure portal and select Manage.

Administre las claves de función en el portal.

Puede obtener claves de función mediante programación con la API de administración de claves.You may obtain function keys programmatically by using Key management API.

Autorización de la clave de APIAPI key authorization

La mayoría de las plantillas de desencadenador HTTP requieren una clave de API en la solicitud.Most HTTP trigger templates require an API key in the request. Por lo tanto, la solicitud HTTP normalmente se parece a la siguiente dirección URL:So your HTTP request normally looks like the following 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.The key can be included in a query string variable named code, as above. También puede incluirse en un encabezado HTTP x-functions-key.It can also be included in an x-functions-key HTTP header. El valor de la clave puede ser cualquier clave de función definida para la función o cualquier clave de host.The value of the key can be any function key defined for the function, or any host key.

Puede permitir solicitudes anónimas, que no requieren claves.You can allow anonymous requests, which do not require keys. También puede exigir que se use la clave principal.You can also require that the master key be used. Cambie el nivel de autorización predeterminado mediante la propiedad authLevel en el JSON de enlace.You change the default authorization level by using the authLevel property in the binding JSON. Para más información, consulte Desencadenador: configuración.For more information, see Trigger - configuration.

Nota

Cuando las funciones se ejecutan localmente, la autorización se deshabilita independientemente del valor del nivel de autenticación especificado.When running functions locally, authorization is disabled regardless of the specified authentication level setting. Después de publicar en Azure, se aplica el valor authLevel del desencadenador.After publishing to Azure, the authLevel setting in your trigger is enforced.

Proteger un punto de conexión HTTP en producciónSecure an HTTP endpoint in production

Para proteger totalmente los puntos de conexión de función en producción, considere la posibilidad de implementar una de las siguientes opciones de seguridad de nivel de aplicación de función:To fully secure your function endpoints in production, you should consider implementing one of the following function app-level security options:

  • Activar la autenticación o autorización de App Service para la aplicación de función.Turn on App Service Authentication / Authorization for your function app. La plataforma App Service permite usar Azure Active Directory (AAD) y varios proveedores de identidades de terceros para autenticar a los clientes.The App Service platform lets use Azure Active Directory (AAD) and several third-party identity providers to authenticate clients. Se puede usar 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.You can use this to implement custom authorization rules for your functions, and you can work with user information from your function code. Para obtener más información, vea Autenticación y autorización en Azure App Service y Uso de identidades de cliente.To learn more, see Authentication and authorization in Azure App Service and Working with client identities.

  • Usar Azure API Management (APIM) para autenticar las solicitudes.Use Azure API Management (APIM) to authenticate requests. APIM proporciona una serie de opciones de seguridad de API para las solicitudes entrantes.APIM provides a variety of API security options for incoming requests. Para obtener más información, vea Directivas de autenticación de Azure API Management.To learn more, see API Management authentication policies. 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.With APIM in place, you can configure your function app to accept requests only from the IP address of your APIM instance. Para obtener más información, vea Restricciones de las direcciones IP.To learn more, see IP address restrictions.

  • Implementar la aplicación de función en una instancia de Azure App Service Environment (ASE).Deploy your function app to an Azure App Service Environment (ASE). ASE proporciona un entorno de hospedaje dedicado en el que ejecutar las funciones.ASE provides a dedicated hosting environment in which to run your functions. ASE le permite configurar una puerta de enlace de front-end única que se puede usar para autenticar todas las solicitudes entrantes.ASE lets you configure a single front-end gateway that you can use to authenticate all incoming requests. Para obtener más información, vea Configuración de un firewall de aplicaciones web (WAF) para entornos de App Service.For more information, see Configuring a Web Application Firewall (WAF) for App Service Environment.

Cuando use alguno de estos métodos de seguridad de nivel de aplicación de función, debe establecer el nivel de autenticación de función desencadenada por HTTP en anonymous.When using one of these function app-level security methods, you should set the HTTP-triggered function authentication level to anonymous.

webhooksWebhooks

Nota

El modo de webhook solo está disponible para la versión 1.x del runtime de Functions.Webhook mode is only available for version 1.x of the Functions runtime. Este cambio se realizó para mejorar el rendimiento de los desencadenadores HTTP en la versión 2.x.This change was made to improve the performance of HTTP triggers in version 2.x.

En la versión 1.x, las plantillas de webhook proporcionan una validación adicional para las cargas de webhook.In version 1.x, webhook templates provide additional validation for webhook payloads. En la versión 2.x, el desencadenador HTTP base todavía funciona y es el modo recomendado para webhooks.In version 2.x, the base HTTP trigger still works and is the recommended approach for webhooks.

Webhooks de GitHubGitHub webhooks

Para responder a webhooks de GitHub, primero cree la función con un desencadenador HTTP y establezca la propiedad webHookType en github.To respond to GitHub webhooks, first create your function with an HTTP Trigger, and set the webHookType property to github. Luego copie su dirección URL y clave de API en la página Agregar webhook del repositorio GitHub.Then copy its URL and API key into the Add webhook page of your GitHub repository.

Webhooks de SlackSlack webhooks

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.The Slack webhook generates a token for you instead of letting you specify it, so you must configure a function-specific key with the token from Slack. Consulte Claves de autorización.See Authorization keys.

Webhooks y clavesWebhooks and keys

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.Webhook authorization is handled by the webhook receiver component, part of the HTTP trigger, and the mechanism varies based on the webhook type. Cada mecanismo se basa en una clave.Each mechanism does rely on a key. De forma predeterminada, se usa la clave de función denominada "default".By default, the function key named "default" is used. 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:To use a different key, configure the webhook provider to send the key name with the request in one of the following ways:

  • 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>.Query string: The provider passes the key name in the clientid query string parameter, such as 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.Request header: The provider passes the key name in the x-functions-clientid header.

Desencadenador: límitesTrigger - limits

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).The HTTP request length is limited to 100 MB (104,857,600 bytes), and the URL length is limited to 4 KB (4,096 bytes). El elemento httpRuntime del archivo Web.config especifica estos límites.These limits are specified by the httpRuntime element of the runtime's Web.config file.

Si una función que usa el desencadenador HTTP no se completa en menos de 2,5 minutos, la puerta de enlace agota el tiempo de espera y devuelve un error HTTP 502.If a function that uses the HTTP trigger doesn't complete within about 2.5 minutes, the gateway will time out and return an HTTP 502 error. La función seguirá ejecutándose, pero no podrá devolver una respuesta HTTP.The function will continue running but will be unable to return an HTTP response. 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.For long-running functions, we recommend that you follow async patterns and return a location where you can ping the status of the request. Para más información sobre cuánto tiempo se puede ejecutar una función, consulte Escalado y hospedaje: Plan de consumo.For information about how long a function can run, see Scale and hosting - Consumption plan.

Desencadenador: propiedades de host.jsonTrigger - host.json properties

El archivo host.json contiene opciones de configuración que controlan el comportamiento de desencadenador HTTP.The host.json file contains settings that control HTTP trigger behavior.

{
    "http": {
        "routePrefix": "api",
        "maxOutstandingRequests": 200,
        "maxConcurrentRequests": 100,
        "dynamicThrottlesEnabled": true
    }
}
PropiedadProperty Valor predeterminadoDefault DESCRIPCIÓNDescription
routePrefixroutePrefix apiapi Prefijo de ruta que se aplica a todas las rutas.The route prefix that applies to all routes. Use una cadena vacía para quitar el prefijo predeterminado.Use an empty string to remove the default prefix.
maxOutstandingRequestsmaxOutstandingRequests 200*200* Número máximo de solicitudes pendientes que se mantienen en un momento dado.The maximum number of outstanding requests that are held at any given time. Este límite incluye las solicitudes que están en cola pero no han empezado a ejecutarse, así como todas las ejecuciones en curso.This limit includes requests that are queued but have not started executing, as well as any in progress executions. Se rechazan todas las solicitudes entrantes que superen este límite con una respuesta 429 "Too Busy" (demasiado ocupado).Any incoming requests over this limit are rejected with a 429 "Too Busy" response. 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.That allows callers to employ time-based retry strategies, and also helps you to control maximum request latencies. Únicamente se controlan los movimientos de la cola que se producen dentro de la ruta de ejecución del host del script.This only controls queuing that occurs within the script host execution path. 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.Other queues such as the ASP.NET request queue will still be in effect and unaffected by this setting. *El valor predeterminado para la versión 1.x es ilimitado (-1).*The default for version 1.x is unbounded (-1). El valor predeterminado para la versión 2.x en un plan de consumo es 200.The default for version 2.x in a consumption plan is 200. El valor predeterminado para la versión 2.x en un plan dedicado es ilimitado (-1).The default for version 2.x in a dedicated plan is unbounded (-1).
maxConcurrentRequestsmaxConcurrentRequests 100*100* Número máximo de funciones HTTP que se ejecutarán en paralelo.The maximum number of http functions that will be executed in parallel. Esto permite controlar la simultaneidad, que a su vez puede ayudar a administrar el uso de recursos.This allows you to control concurrency, which can help manage resource utilization. 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.For example, you might have an http function that uses a lot of system resources (memory/cpu/sockets) such that it causes issues when concurrency is too high. 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.Or you might have a function that makes outbound requests to a third party service, and those calls need to be rate limited. En estos casos puede ayudar aplicar una limitación.In these cases, applying a throttle here can help. *El valor predeterminado para la versión 1.x es ilimitado (-1).*The default for version 1.x is unbounded (-1). El valor predeterminado para la versión 2.x en un plan de consumo es 100.The default for version 2.x in a consumption plan is 100. El valor predeterminado para la versión 2.x en un plan dedicado es ilimitado (-1).The default for version 2.x in a dedicated plan is unbounded (-1).
dynamicThrottlesEnableddynamicThrottlesEnabled true*true* 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 rechazarán con una respuesta 429 "Ocupado" hasta que los contadores vuelvan a niveles normales.When enabled, this setting causes the request processing pipeline to periodically check system performance counters like connections/threads/processes/memory/cpu/etc. and if any of those counters are over a built-in high threshold (80%), requests will be rejected with a 429 "Too Busy" response until the counter(s) return to normal levels. *El valor predeterminado para la versión 1.x es false.*The default for version 1.x is false. El valor predeterminado para la versión 2.x en un plan de consumo es true.The default for version 2.x in a consumption plan is true. El valor predeterminado para la versión 2.x en un plan dedicado es false.The default for version 2.x in a dedicated plan is false.

OutputOutput

Use el enlace de salida HTTP para responder al remitente de la solicitud HTTP.Use the HTTP output binding to respond to the HTTP request sender. Este enlace requiere un desencadenador HTTP y le permite personalizar la respuesta asociada con la solicitud del desencadenador.This binding requires an HTTP trigger and allows you to customize the response associated with the trigger's request. Si no se proporciona un enlace de salida HTTP, un desencadenador HTTP devuelve HTTP 200 OK con un cuerpo vacío en Functions 1.x, o HTTP 204 No Content con un cuerpo vacío en Functions 2.x.If an HTTP output binding is not provided, an HTTP trigger returns HTTP 200 OK with an empty body in Functions 1.x, or HTTP 204 No Content with an empty body in Functions 2.x.

Salida: configuraciónOutput - configuration

En la siguiente tabla se explican las propiedades de configuración de enlace que se establecen en el archivo function.json.The following table explains the binding configuration properties that you set in the function.json file. En las bibliotecas de clases de C#, no hay ninguna propiedad de atributo que corresponda a estas propiedades function.json.For C# class libraries, there are no attribute properties that correspond to these function.json properties.

PropiedadProperty DESCRIPCIÓNDescription
typetype Se debe establecer en http.Must be set to http.
direccióndirection Se debe establecer en out.Must be set to out.
namename Nombre de la variable usado en el código de la función para la respuesta, o $return para usar el valor devuelto.The variable name used in function code for the response, or $return to use the return value.

Uso de salidasOutput - usage

Para enviar una respuesta HTTP, use los patrones de respuesta estándar del lenguaje.To send an HTTP response, use the language-standard response patterns. En C# o un script de C#, haga que la función devuelva el tipo IActionResult o Task<IActionResult>.In C# or C# script, make the function return type IActionResult or Task<IActionResult>. En C#, no se requiere un atributo de valor devuelto.In C#, a return value attribute isn't required.

Para obtener respuestas de ejemplo, vea el ejemplo de desencadenador.For example responses, see the trigger example.

Pasos siguientesNext steps

Más información sobre desencadenadores y enlaces de Azure FunctionsLearn more about Azure functions triggers and bindings