Azure Functions gatilhos e associações HTTPAzure Functions HTTP triggers and bindings

Este artigo explica como trabalhar com gatilhos HTTP e associações de saída no Azure Functions.This article explains how to work with HTTP triggers and output bindings in Azure Functions.

Um gatilho HTTP pode ser personalizado para responder a WebHooks.An HTTP trigger can be customized to respond to webhooks.

Estas são informações de referência para programadores das funções do Azure.This is reference information for Azure Functions developers. Se estiver familiarizado com as funções do Azure, comece com os seguintes recursos:If you're new to Azure Functions, start with the following resources:

Dica

Se planeja usar os enlaces de HTTP ou WebHook, planeie evitar o esgotamento de porta que pode ser causado por instâncias impróprias 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 obter mais informações, consulte como gerir ligações nas funções do Azure.For more information, see How to manage connections in Azure Functions.

O código neste artigo usa como padrão a sintaxe do Functions 2. x, que usa o .NET Core.The code in this article defaults to Functions 2.x syntax which uses .NET Core. Para obter informações sobre a sintaxe 1. x, consulte os modelos de funções 1. x.For information on the 1.x syntax, see the 1.x functions templates.

Pacotes - funções 1.xPackages - Functions 1.x

As associações HTTP são fornecidas no pacote NuGet Microsoft. Azure. webjobs. Extensions. http , versão 1. x.The HTTP bindings are provided in the Microsoft.Azure.WebJobs.Extensions.Http NuGet package, version 1.x. O código-fonte do pacote está no repositório GitHub Azure-webjobs-SDK-Extensions .Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

Suporte para essa ligação é fornecido automaticamente em todos os ambientes de desenvolvimento.Support for this binding is automatically provided in all development environments. Não é preciso instalar o pacote ou Registre-se a extensão manualmente.You don't have to manually install the package or register the extension.

Pacotes - funções 2.xPackages - Functions 2.x

As associações HTTP são fornecidas no pacote NuGet Microsoft. Azure. webjobs. Extensions. http , versão 3. x.The HTTP bindings are provided in the Microsoft.Azure.WebJobs.Extensions.Http NuGet package, version 3.x. O código-fonte do pacote está no repositório GitHub Azure-webjobs-SDK-Extensions .Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

Suporte para essa ligação é fornecido automaticamente em todos os ambientes de desenvolvimento.Support for this binding is automatically provided in all development environments. Não é preciso instalar o pacote ou Registre-se a extensão manualmente.You don't have to manually install the package or register the extension.

AcionadorTrigger

O gatilho HTTP permite invocar uma função com uma solicitação HTTP.The HTTP trigger lets you invoke a function with an HTTP request. Você pode usar um gatilho HTTP para criar APIs sem servidor e responder a WebHooks.You can use an HTTP trigger to build serverless APIs and respond to webhooks.

Por padrão, um gatilho HTTP retorna HTTP 200 OK com um corpo vazio em Functions 1. x ou HTTP 204 sem conteúdo com um corpo vazio no 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 a resposta, configure uma Associação de saída http.To modify the response, configure an HTTP output binding.

Acionador - exemploTrigger - example

Veja o exemplo de idioma específico:See the language-specific example:

Acionador - exemplo do c#Trigger - C# example

O exemplo a seguir mostra uma C# função que procura um parâmetro name na cadeia de caracteres de consulta ou no corpo da solicitação 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. Observe que o valor de retorno é usado para a associação de saída, mas um atributo de valor de retorno não é necessário.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");
}

Acionador - exemplo de script do c#Trigger - C# script example

O exemplo a seguir mostra uma associação de gatilho em um arquivo Function. JSON e uma C# função de script que usa a associação.The following example shows a trigger binding in a function.json file and a C# script function that uses the binding. A função procura um parâmetro name na cadeia de caracteres de consulta ou no corpo da solicitação HTTP.The function looks for a name parameter either in the query string or the body of the HTTP request.

Aqui está o Function ficheiro: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"
        }
    ]
}

O configuração seção explica essas propriedades.The configuration section explains these properties.

Aqui está C# o código de script que se associa 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");
}

Você pode associar a um objeto personalizado em vez de HttpRequest.You can bind to a custom object instead of HttpRequest. Esse objeto é criado a partir do corpo da solicitação e analisado como JSON.This object is created from the body of the request and parsed as JSON. Da mesma forma, um tipo pode ser passado para a associação de saída de resposta HTTP e retornado como o corpo da resposta, junto com um código de status 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;}
}

Acionador - F# exemploTrigger - F# example

O exemplo a seguir mostra uma associação de gatilho em um arquivo Function. JSON e uma F# função que usa a associação.The following example shows a trigger binding in a function.json file and an F# function that uses the binding. A função procura um parâmetro name na cadeia de caracteres de consulta ou no corpo da solicitação HTTP.The function looks for a name parameter either in the query string or the body of the HTTP request.

Aqui está o Function ficheiro:Here's the function.json file:

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

O configuração seção explica essas propriedades.The configuration section explains these properties.

Aqui está o F# código: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

Você precisa de um arquivo project.json que usa o NuGet para fazer referência aos assemblies FSharp.Interop.Dynamic e Dynamitey, conforme mostrado no exemplo a seguir: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"
      }
    }
  }
}

Acionador - exemplo de JavaScriptTrigger - JavaScript example

O exemplo a seguir mostra uma associação de gatilho em um arquivo Function. JSON e uma função JavaScript que usa a associação.The following example shows a trigger binding in a function.json file and a JavaScript function that uses the binding. A função procura um parâmetro name na cadeia de caracteres de consulta ou no corpo da solicitação HTTP.The function looks for a name parameter either in the query string or the body of the HTTP request.

Aqui está o Function ficheiro:Here's the function.json file:

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

O configuração seção explica essas propriedades.The configuration section explains these properties.

Eis o código 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();
};

Gatilho-exemplo de PythonTrigger - Python example

O exemplo a seguir mostra uma associação de gatilho em um arquivo Function. JSON e uma função Python que usa a associação.The following example shows a trigger binding in a function.json file and a Python function that uses the binding. A função procura um parâmetro name na cadeia de caracteres de consulta ou no corpo da solicitação HTTP.The function looks for a name parameter either in the query string or the body of the HTTP request.

Aqui está o Function ficheiro: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"
        }
    ]
}

O configuração seção explica essas propriedades.The configuration section explains these properties.

Este é o código 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
        )

Gatilho-exemplos de JavaTrigger - Java examples

Os exemplos a seguir mostram a associação de gatilho HTTP em um arquivo Function. JSON e as respectivas funções Java que usam a associação.The following examples show the HTTP trigger binding in a function.json file and the respective Java functions that use the binding.

Aqui está o Function ficheiro:Here's the function.json file:

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

Parâmetro de leitura da cadeia de caracteres de consulta (Java)Read parameter from the query string (Java)

Este exemplo lê um parâmetro, chamado id, da cadeia de caracteres de consulta e o usa para criar um documento JSON retornado ao cliente, com o tipo de conteúdo 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();
        }
    }

Ler o corpo de uma solicitação POST (Java)Read body from a POST request (Java)

Este exemplo lê o corpo de uma solicitação POST, como um String, e a usa para criar um documento JSON retornado ao cliente, com o tipo de conteúdo 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();
        }
    }

Ler parâmetro de uma rota (Java)Read parameter from a route (Java)

Este exemplo lê um parâmetro obrigatório, chamado id, e um parâmetro opcional name do caminho de rota e os usa para criar um documento JSON retornado ao cliente, com o tipo de conteúdo 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. QT

    @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();
        }
    }

Ler o corpo do POJO de uma solicitação POST (Java)Read POJO body from a POST request (Java)

Este é o código para a classe ToDoItem, referenciada neste exemplo: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 + "}";
  }
}

Este exemplo lê o corpo de uma solicitação POST.This example reads the body of a POST request. O corpo da solicitação é desserializado automaticamente em um objeto ToDoItem e é retornado para o cliente, com o tipo de conteúdo application/json.The request body gets automatically de-serialized into a ToDoItem object, and is returned to the client, with content type application/json. O parâmetro ToDoItem é serializado pelo tempo de execução do functions, pois ele é atribuído à propriedade body da classe 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();
        }
    }

Acionador - atributosTrigger - attributes

Em C# bibliotecas de classes, use o atributo HttpTrigger .In C# class libraries, use the HttpTrigger attribute.

Você pode definir o nível de autorização e os métodos HTTP permitidos em parâmetros de construtor de atributo e há propriedades para tipo de webhook e modelo de rota.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 obter mais informações sobre essas configurações, consulte gatilho-configuração.For more information about these settings, see Trigger - configuration. Aqui está um atributo HttpTrigger em uma assinatura 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 obter um exemplo completo, consulte acionador - exemplo do c#.For a complete example, see Trigger - C# example.

Acionador - configuraçãoTrigger - configuration

A tabela seguinte explica as propriedades de configuração de ligação definida no Function ficheiro e o HttpTrigger atributo.The following table explains the binding configuration properties that you set in the function.json file and the HttpTrigger attribute.

propriedade de Functionfunction.json property Propriedade de atributoAttribute property DescriçãoDescription
typetype n/dn/a Obrigatório-deve ser definido como httpTrigger.Required - must be set to httpTrigger.
directiondirection n/dn/a Obrigatório-deve ser definido como in.Required - must be set to in.
namename n/dn/a Obrigatório-o nome da variável usada no código de função para a solicitação ou o corpo da solicitação.Required - the variable name used in function code for the request or request body.
authLevelauthLevel AuthLevelAuthLevel Determina quais chaves, se houver, precisam estar presentes na solicitação para invocar a função.Determines what keys, if any, need to be present on the request in order to invoke the function. O nível de autorização pode ser um dos seguintes valores:The authorization level can be one of the following values:
  • a chave de API anonymous @ no__t-1No é necessária.anonymous—No API key is required.
  • function @ no__t-1A a chave de API específica da função é necessária.function—A function-specific API key is required. Esse será o valor padrão se nenhum for fornecido.This is the default value if none is provided.
  • admin @ no__t-1a chave mestra é necessária.admin—The master key is required.
Para obter mais informações, consulte a seção sobre chaves de autorização.For more information, see the section about authorization keys.
methodsmethods MethodsMethods Uma matriz dos métodos HTTP para os quais a função responde.An array of the HTTP methods to which the function responds. Se não for especificado, a função responderá a todos os métodos HTTP.If not specified, the function responds to all HTTP methods. Consulte Personalizar o ponto de extremidade http.See customize the http endpoint.
rotaroute RotaRoute Define o modelo de rota, controlando a quais URLs de solicitação sua função responde.Defines the route template, controlling to which request URLs your function responds. O valor padrão, se nenhum for fornecido, será <functionname>.The default value if none is provided is <functionname>. Para obter mais informações, consulte Personalizar o ponto de extremidade http.For more information, see customize the http endpoint.
webHookTypewebHookType WebHookTypeWebHookType Com suporte apenas para o tempo de execução da versão 1. x.Supported only for the version 1.x runtime.

Configura o gatilho HTTP para atuar como um receptor de webhook para o provedor especificado.Configures the HTTP trigger to act as a webhook receiver for the specified provider. Não defina a propriedade methods se você definir essa propriedade.Don't set the methods property if you set this property. O tipo de webhook pode ser um dos seguintes valores:The webhook type can be one of the following values:
  • genericJson @ no__t-1A ponto de extremidade de webhook de finalidade geral sem lógica para um provedor específico.genericJson—A general-purpose webhook endpoint without logic for a specific provider. Essa configuração restringe as solicitações para apenas as que usam HTTP POST e com o tipo de conteúdo application/json.This setting restricts requests to only those using HTTP POST and with the application/json content type.
  • github @ no__t-1a função responde a WebHooks do GitHub.github—The function responds to GitHub webhooks. Não use a propriedade authLevel com WebHooks do github.Do not use the authLevel property with GitHub webhooks. Para obter mais informações, consulte a seção WebHooks do GitHub posteriormente neste artigo.For more information, see the GitHub webhooks section later in this article.
  • slack @ no__t-1a função responde a WebHooks de margem de atraso.slack—The function responds to Slack webhooks. Não use a propriedade authLevel com WebHooks de margem de atraso.Do not use the authLevel property with Slack webhooks. Para obter mais informações, consulte a seção da margem de atraso WebHooks posteriormente neste artigo.For more information, see the Slack webhooks section later in this article.

Acionador - utilizaçãoTrigger - usage

Para C# funções F# e, você pode declarar o tipo de sua entrada de gatilho para ser HttpRequest ou um tipo personalizado.For C# and F# functions, you can declare the type of your trigger input to be either HttpRequest or a custom type. Se você escolher HttpRequest, obterá acesso completo ao objeto de solicitação.If you choose HttpRequest, you get full access to the request object. Para um tipo personalizado, o tempo de execução tenta analisar o corpo da solicitação JSON para definir as propriedades do objeto.For a custom type, the runtime tries to parse the JSON request body to set the object properties.

Para funções de JavaScript, o tempo de execução do Functions fornece o corpo da solicitação em vez do objeto de solicitação.For JavaScript functions, the Functions runtime provides the request body instead of the request object. Para obter mais informações, consulte o exemplo de gatilho de JavaScript.For more information, see the JavaScript trigger example.

Personalizar o ponto de extremidade HTTPCustomize the HTTP endpoint

Por padrão, quando você cria uma função para um gatilho HTTP, a função é endereçável com uma rota do formulário: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>

Você pode personalizar essa rota usando a propriedade opcional route na associação de entrada do gatilho HTTP.You can customize this route using the optional route property on the HTTP trigger's input binding. Por exemplo, o arquivo Function. JSON a seguir define uma propriedade route para um gatilho 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"
    }
    ]
}

Usando essa configuração, a função é agora endereçável com a rota a seguir em vez da rota 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

Isso permite que o código de função dê suporte a dois parâmetros no endereço, na categoria e na ID. Você pode usar qualquer restrição de rota da API Web com seus 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. O código C# de função a seguir usa ambos os 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}");
}

Aqui está o código de função node. js que usa os mesmos parâmetros de rota.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();
}

Por padrão, todas as rotas de função são prefixadas com a API.By default, all function routes are prefixed with api. Você também pode personalizar ou remover o prefixo usando a propriedade http.routePrefix em seu arquivo host. JSON .You can also customize or remove the prefix using the http.routePrefix property in your host.json file. O exemplo a seguir remove o prefixo de rota da API usando uma cadeia de caracteres vazia para o prefixo no arquivo 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": ""
    }
}

Trabalhando com identidades de clienteWorking with client identities

Se seu aplicativo de funções estiver usando a autenticação/autorização do serviço de aplicativo, você poderá exibir informações sobre clientes autenticados do seu código.If your function app is using App Service Authentication / Authorization, you can view information about authenticated clients from your code. Essas informações estão disponíveis como cabeçalhos de solicitação injetados pela plataforma.This information is available as request headers injected by the platform.

Você também pode ler essas informações de dados de associação.You can also read this information from binding data. Esse recurso só está disponível para o tempo de execução do Functions 2. x.This capability is only available to the Functions 2.x runtime. Ele também está disponível apenas para linguagens .NET.It is also currently only available for .NET languages.

Em linguagens .NET, essas informações estão disponíveis como um ClaimsPrincipal.In .NET languages, this information is available as a ClaimsPrincipal. O ClaimsPrincipal está disponível como parte do contexto da solicitação, conforme mostrado no exemplo a seguir: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, o ClaimsPrincipal pode simplesmente ser incluído como um parâmetro adicional na assinatura da função: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;
}

Chaves de autorizaçãoAuthorization keys

As funções permitem usar chaves para tornar mais difícil acessar seus pontos de extremidade de função HTTP durante o desenvolvimento.Functions lets you use keys to make it harder to access your HTTP function endpoints during development. Um gatilho HTTP padrão pode exigir que tal chave de API esteja presente na solicitação.A standard HTTP trigger may require such an API key be present in the request.

Importante

Embora as chaves possam ajudar a ofuscar seus pontos de extremidade HTTP durante o desenvolvimento, elas não são pretendidas como uma maneira de proteger um gatilho HTTP na produção.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 saber mais, confira proteger um ponto de extremidade http em produção.To learn more, see Secure an HTTP endpoint in production.

Nota

No tempo de execução do Functions 1. x, os provedores de webhook podem usar chaves para autorizar solicitações de várias maneiras, dependendo do suporte do provedor.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. Isso é abordado em WebHooks e chaves.This is covered in Webhooks and keys. O tempo de execução da versão 2. x não inclui suporte interno para provedores de webhook.The version 2.x runtime does not include built-in support for webhook providers.

Há dois tipos de chaves:There are two types of keys:

  • Chaves de host: Essas chaves são compartilhadas por todas as funções no aplicativo de funções.Host keys: These keys are shared by all functions within the function app. Quando usado como uma chave de API, eles permitem o acesso a qualquer função dentro do aplicativo de funções.When used as an API key, these allow access to any function within the function app.
  • Teclas de função: Essas chaves se aplicam somente às funções específicas sob as quais elas são definidas.Function keys: These keys apply only to the specific functions under which they are defined. Quando usado como uma chave de API, eles só permitem o acesso a essa função.When used as an API key, these only allow access to that function.

Cada chave é nomeada para referência, e há uma chave padrão (denominada "padrão") no nível da função e do host.Each key is named for reference, and there is a default key (named "default") at the function and host level. As teclas de função têm precedência sobre as chaves de host.Function keys take precedence over host keys. Quando duas chaves são definidas com o mesmo nome, a tecla de função sempre é usada.When two keys are defined with the same name, the function key is always used.

Cada aplicativo de funções também tem uma chave mestraespecial.Each function app also has a special master key. Essa chave é uma chave de host chamada _master, que fornece acesso administrativo às APIs de tempo de execução.This key is a host key named _master, which provides administrative access to the runtime APIs. Esta chave não pode ser revogada.This key cannot be revoked. Quando você define um nível de autorização de admin, as solicitações devem usar a chave mestra; qualquer outra chave resulta em falha de autorização.When you set an authorization level of admin, requests must use the master key; any other key results in authorization failure.

Atenção

Devido às permissões elevadas em seu aplicativo de funções concedidas pela chave mestra, você não deve compartilhar essa chave com terceiros ou distribuí-la em aplicativos cliente nativos.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. Tome cuidado ao escolher o nível de autorização do administrador.Use caution when choosing the admin authorization level.

Obtendo chavesObtaining keys

As chaves são armazenadas como parte do seu aplicativo de funções no Azure e são criptografadas em repouso.Keys are stored as part of your function app in Azure and are encrypted at rest. Para exibir suas chaves, criar novas ou reverter chaves para novos valores, navegue até uma das funções disparadas por HTTP no portal do Azure e selecione gerenciar.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.

Gerenciar chaves de função no Portal.

Você pode obter as chaves de função programaticamente usando APIs de gerenciamento de chaves.You may obtain function keys programmatically by using Key management APIs.

Autorização de chave de APIAPI key authorization

A maioria dos modelos de gatilho HTTP exigem uma chave de API na solicitação.Most HTTP trigger templates require an API key in the request. Portanto, sua solicitação HTTP normalmente se parece com a seguinte URL:So your HTTP request normally looks like the following URL:

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

A chave pode ser incluída em uma variável de cadeia de caracteres de consulta chamada code, como acima.The key can be included in a query string variable named code, as above. Ele também pode ser incluído em um cabeçalho HTTP x-functions-key.It can also be included in an x-functions-key HTTP header. O valor da chave pode ser qualquer chave de função definida para a função ou qualquer chave de host.The value of the key can be any function key defined for the function, or any host key.

Você pode permitir solicitações anônimas, que não exigem chaves.You can allow anonymous requests, which do not require keys. Você também pode exigir que a chave mestra seja usada.You can also require that the master key be used. Você altera o nível de autorização padrão usando a propriedade authLevel no JSON de associação.You change the default authorization level by using the authLevel property in the binding JSON. Para obter mais informações, consulte gatilho-configuração.For more information, see Trigger - configuration.

Nota

Ao executar funções localmente, a autorização é desabilitada, independentemente da configuração do nível de autenticação especificado.When running functions locally, authorization is disabled regardless of the specified authentication level setting. Após a publicação no Azure, a configuração authLevel em seu gatilho é imposta.After publishing to Azure, the authLevel setting in your trigger is enforced. As chaves ainda são necessárias ao executar localmente em um contêiner.Keys are still required when running locally in a container.

Proteger um ponto de extremidade HTTP na produçãoSecure an HTTP endpoint in production

Para proteger totalmente seus pontos de extremidade de função em produção, você deve considerar a implementação de uma das seguintes opções de segurança no nível do aplicativo de funções:To fully secure your function endpoints in production, you should consider implementing one of the following function app-level security options:

  • Ative a autenticação/autorização do serviço de aplicativo para seu aplicativo de funções.Turn on App Service Authentication / Authorization for your function app. A plataforma do serviço de aplicativo permite usar Azure Active Directory (AAD) e vários provedores de identidade de terceiros para autenticar clientes.The App Service platform lets use Azure Active Directory (AAD) and several third-party identity providers to authenticate clients. Você pode usar isso para implementar regras de autorização personalizadas para suas funções e pode trabalhar com informações de usuário do seu código de função.You can use this to implement custom authorization rules for your functions, and you can work with user information from your function code. Para saber mais, consulte autenticação e autorização no serviço Azure app e trabalhando com identidades de cliente.To learn more, see Authentication and authorization in Azure App Service and Working with client identities.

  • Use o APIM (gerenciamento de API do Azure) para autenticar solicitações.Use Azure API Management (APIM) to authenticate requests. O APIM fornece uma variedade de opções de segurança de API para solicitações de entrada.APIM provides a variety of API security options for incoming requests. Para saber mais, consulte políticas de autenticação de gerenciamento de API.To learn more, see API Management authentication policies. Com o APIM em vigor, você pode configurar seu aplicativo de funções para aceitar solicitações somente do endereço IP da sua instância do APIM.With APIM in place, you can configure your function app to accept requests only from the IP address of your APIM instance. Para saber mais, consulte restrições de endereço IP.To learn more, see IP address restrictions.

  • Implante seu aplicativo de funções em um Ambiente do Serviço de Aplicativo do Azure (ASE).Deploy your function app to an Azure App Service Environment (ASE). O ASE fornece um ambiente de hospedagem dedicado no qual executar suas funções.ASE provides a dedicated hosting environment in which to run your functions. O ASE permite configurar um único gateway de front-end que você pode usar para autenticar todas as solicitações de entrada.ASE lets you configure a single front-end gateway that you can use to authenticate all incoming requests. Para obter mais informações, consulte Configurando um WAF (firewall do aplicativo Web) para ambiente do serviço de aplicativo.For more information, see Configuring a Web Application Firewall (WAF) for App Service Environment.

Ao usar um desses métodos de segurança de nível de aplicativo de função, você deve definir o nível de autenticação da função disparada por HTTP como anonymous.When using one of these function app-level security methods, you should set the HTTP-triggered function authentication level to anonymous.

WebhooksWebhooks

Nota

O modo de webhook só está disponível para a versão 1. x do tempo de execução do functions.Webhook mode is only available for version 1.x of the Functions runtime. Essa alteração foi feita para melhorar o desempenho de gatilhos HTTP na versão 2. x.This change was made to improve the performance of HTTP triggers in version 2.x.

Na versão 1. x, os modelos de webhook fornecem validação adicional para cargas de webhook.In version 1.x, webhook templates provide additional validation for webhook payloads. Na versão 2. x, o gatilho HTTP base ainda funciona e é a abordagem recomendada para WebHooks.In version 2.x, the base HTTP trigger still works and is the recommended approach for webhooks.

WebHooks do GitHubGitHub webhooks

Para responder a WebHooks do GitHub, primeiro crie sua função com um gatilho HTTP e defina a propriedade Webhooktype como github.To respond to GitHub webhooks, first create your function with an HTTP Trigger, and set the webHookType property to github. Em seguida, copie sua URL e a chave de API na página Adicionar webhook do seu repositório github.Then copy its URL and API key into the Add webhook page of your GitHub repository.

Subganchos de margem de atrasoSlack webhooks

O webhook de margem de atraso gera um token para você em vez de permitir que você o especifique, portanto, você deve configurar uma chave específica de função com o token da margem de atraso.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 chaves de autorização.See Authorization keys.

WebHooks e chavesWebhooks and keys

A autorização de webhook é tratada pelo componente receptor de webhook, parte do gatilho HTTP e o mecanismo varia de acordo com o 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 depende de uma chave.Each mechanism does rely on a key. Por padrão, a chave de função chamada "default" é usada.By default, the function key named "default" is used. Para usar uma chave diferente, configure o provedor de webhook para enviar o nome da chave com a solicitação de uma das seguintes maneiras:To use a different key, configure the webhook provider to send the key name with the request in one of the following ways:

  • Cadeia de caracteres de consulta: O provedor passa o nome da chave no parâmetro de cadeia de caracteres 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>.
  • Cabeçalho da solicitação: O provedor passa o nome da chave no cabeçalho x-functions-clientid.Request header: The provider passes the key name in the x-functions-clientid header.

Gatilho-limitesTrigger - limits

O comprimento da solicitação HTTP é limitado a 100 MB (104.857.600 bytes) e o comprimento da URL é limitado 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). Esses limites são especificados pelo elemento httpRuntime do arquivo Web. configdo tempo de execução.These limits are specified by the httpRuntime element of the runtime's Web.config file.

Se uma função que usa o gatilho HTTP não for concluída em cerca de 2,5 minutos, o gateway atingirá o tempo limite e retornará um erro 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. A função continuará em execução, mas não poderá retornar uma resposta HTTP.The function will continue running but will be unable to return an HTTP response. Para funções de execução longa, recomendamos que você siga os padrões assíncronos e retorne um local em que você possa executar o ping do status da solicitação.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 obter informações sobre quanto tempo uma função pode ser executada, consulte escala e hospedagem – plano de consumo.For information about how long a function can run, see Scale and hosting - Consumption plan.

Acionador - propriedades de Host. JSONTrigger - host.json properties

O arquivo host. JSON contém configurações que controlam o comportamento do gatilho http.The host.json file contains settings that control HTTP trigger behavior.

PropriedadeProperty PredefiniçãoDefault DescriçãoDescription
routePrefixroutePrefix apiapi O prefixo de rota que se aplica a todas as rotas.The route prefix that applies to all routes. Use uma cadeia de caracteres vazia para remover o prefixo padrão.Use an empty string to remove the default prefix.
maxOutstandingRequestsmaxOutstandingRequests 200*200* O número máximo de solicitações pendentes que são mantidas em um determinado momento.The maximum number of outstanding requests that are held at any given time. Esse limite inclui solicitações que estão na fila, mas não iniciaram a execução, bem como qualquer execução em andamento.This limit includes requests that are queued but have not started executing, as well as any in progress executions. Todas as solicitações de entrada acima desse limite são rejeitadas com uma resposta de 429 "muito ocupado".Any incoming requests over this limit are rejected with a 429 "Too Busy" response. Isso permite que os chamadores empreguem estratégias de repetição baseadas em tempo, além de ajudar você a controlar as latências de solicitação máximas.That allows callers to employ time-based retry strategies, and also helps you to control maximum request latencies. Isso controla somente o enfileiramento que ocorre no caminho de execução do host de script.This only controls queuing that occurs within the script host execution path. Outras filas, como a fila de solicitações ASP.NET, ainda estarão em vigor e não serão afetadas por essa configuração.Other queues such as the ASP.NET request queue will still be in effect and unaffected by this setting. * O padrão para a versão 1. x é não associado (-1).*The default for version 1.x is unbounded (-1). O padrão para a versão 2. x em um plano de consumo é 200.The default for version 2.x in a consumption plan is 200. O padrão para a versão 2. x em um plano dedicado não está associado (-1).The default for version 2.x in a dedicated plan is unbounded (-1).
maxConcurrentRequestsmaxConcurrentRequests 100*100* O número máximo de funções http que serão executadas em paralelo.The maximum number of http functions that will be executed in parallel. Isso permite que você controle a simultaneidade, o que pode ajudar a gerenciar a utilização de recursos.This allows you to control concurrency, which can help manage resource utilization. Por exemplo, você pode ter uma função http que usa muitos recursos do sistema (memória/CPU/soquetes), de modo que isso cause problemas quando a simultaneidade for muito 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. Ou você pode ter uma função que faça solicitações de saída para um serviço de terceiros, e essas chamadas precisam ser limitadas por taxa.Or you might have a function that makes outbound requests to a third party service, and those calls need to be rate limited. Nesses casos, a aplicação de uma limitação aqui pode ajudar.In these cases, applying a throttle here can help. * O padrão para a versão 1. x é não associado (-1).*The default for version 1.x is unbounded (-1). O padrão para a versão 2. x em um plano de consumo é 100.The default for version 2.x in a consumption plan is 100. O padrão para a versão 2. x em um plano dedicado não está associado (-1).The default for version 2.x in a dedicated plan is unbounded (-1).
dynamicThrottlesEnableddynamicThrottlesEnabled verdadeiro*true* Quando habilitado, essa configuração faz com que o pipeline de processamento de solicitações Verifique periodicamente os contadores de desempenho do sistema como conexões/threads/processos/memória/CPU/etc. e, se qualquer um desses contadores estiver acima de um limite alto interno (80%), as solicitações serão rejeitado com uma resposta de 429 "muito ocupado" até que os contadores retornem aos níveis normais.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. * O padrão para a versão 1. x é false.*The default for version 1.x is false. O padrão para a versão 2. x em um plano de consumo é true.The default for version 2.x in a consumption plan is true. O padrão para a versão 2. x em um plano dedicado é false.The default for version 2.x in a dedicated plan is false.

OutputOutput

Use a associação de saída HTTP para responder ao remetente da solicitação HTTP.Use the HTTP output binding to respond to the HTTP request sender. Essa associação requer um gatilho HTTP e permite que você personalize a resposta associada à solicitação do gatilho.This binding requires an HTTP trigger and allows you to customize the response associated with the trigger's request. Se uma associação de saída HTTP não for fornecida, um gatilho HTTP retornará HTTP 200 OK com um corpo vazio em Functions 1. x ou HTTP 204 sem conteúdo com um corpo vazio no 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.

Saída - configuraçãoOutput - configuration

A tabela a seguir explica as propriedades de configuração de associação que você definiu no arquivo Function. JSON .The following table explains the binding configuration properties that you set in the function.json file. Para C# bibliotecas de classes, não há propriedades de atributo que correspondam a essas propriedades Function. JSON .For C# class libraries, there are no attribute properties that correspond to these function.json properties.

PropriedadeProperty DescriçãoDescription
typetype Tem de ser definido como http.Must be set to http.
directiondirection Tem de ser definido como out.Must be set to out.
namename O nome da variável usada no código de função para a resposta ou $return para usar o valor de retorno.The variable name used in function code for the response, or $return to use the return value.

Saída - utilizaçãoOutput - usage

Para enviar uma resposta HTTP, use os padrões de resposta padrão de idioma.To send an HTTP response, use the language-standard response patterns. Em C# ou C# script, torne o tipo de retorno da função IActionResult ou Task<IActionResult>.In C# or C# script, make the function return type IActionResult or Task<IActionResult>. No C#, um atributo de valor de retorno não é necessário.In C#, a return value attribute isn't required.

Por exemplo, respostas, consulte o exemplo de gatilho.For example responses, see the trigger example.

Passos seguintesNext steps

Saiba mais sobre as funções do Azure acionadores e enlacesLearn more about Azure functions triggers and bindings