Associazioni HTTP e webhook in Funzioni di AzureAzure Functions HTTP and webhook bindings

Questo articolo illustra come usare le associazioni HTTP in Funzioni di Azure.This article explains how to work with HTTP bindings in Azure Functions. Funzioni di Azure supporta il trigger HTTP e le associazioni di output.Azure Functions supports HTTP triggers and output bindings.

Un trigger HTTP può essere personalizzato per rispondere ai webhook.An HTTP trigger can be customized to respond to webhooks. Un trigger webhook accetta solo un payload JSON e convalida l'oggetto JSON.A webhook trigger accepts only a JSON payload and validates the JSON. Esistono versioni speciali di trigger webhook che semplificano la gestione dei webhook da alcuni provider, ad esempio GitHub e Slack.There are special versions of the webhook trigger that make it easier to handle webhooks from certain providers, such as GitHub and Slack.

Informazioni di riferimento per gli sviluppatori delle Funzioni di Azure.This is reference information for Azure Functions developers. Se non si ha familiarità con le Funzioni di Azure, iniziare con le seguenti risorse:If you're new to Azure Functions, start with the following resources:

Suggerimento

Se si prevede di usare binding HTTP o WebHook, evitare l'esaurimento delle porte che può essere causato da un'errata creazione di istanze di 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. Per altre informazioni, vedere l'articolo Improper Instantiation antipattern (Antipattern non valido per la creazione di istanze).For more information, review the article Improper Instantiation antipattern.

TriggerTrigger

Un trigger HTTP consente di richiamare una funzione con una richiesta HTTPThe HTTP trigger lets you invoke a function with an HTTP request. e può essere usato per compilare API senza server e rispondere ai webhook.You can use an HTTP trigger to build serverless APIs and respond to webhooks.

Per impostazione predefinita, un trigger HTTP risponde alla richiesta con un codice di stato HTTP 200 OK e un corpo vuoto.By default, an HTTP trigger responds to the request with an HTTP 200 OK status code and an empty body. Per modificare la risposta, configurare un'associazione di output HTTP.To modify the response, configure an HTTP output binding.

Trigger - esempioTrigger - example

Vedere l'esempio specifico per ciascun linguaggio:See the language-specific example:

Trigger - esempio in C#Trigger - C# example

Nell'esempio seguente un funzione c# che cerca un name parametro nella stringa di query o il corpo della richiesta 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.

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

    // parse query parameter
    string name = req.GetQueryNameValuePairs()
        .FirstOrDefault(q => string.Compare(q.Key, "name", true) == 0)
        .Value;

    // Get request body
    dynamic data = await req.Content.ReadAsAsync<object>();

    // Set name to query string or body data
    name = name ?? data?.name;

    return name == null
        ? req.CreateResponse(HttpStatusCode.BadRequest, "Please pass a name on the query string or in the request body")
        : req.CreateResponse(HttpStatusCode.OK, "Hello " + name);
}

Trigger - esempio di script C#Trigger - C# script example

L'esempio seguente mostra un'associazione di trigger in un file function.json e una funzione script C# che usa l'associazione.The following example shows a trigger binding in a function.json file and a C# script function that uses the binding. La funzione cerca un parametro name nella stringa di query o nel corpo della richiesta HTTP.The function looks for a name parameter either in the query string or the body of the HTTP request.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

{
    "name": "req",
    "type": "httpTrigger",
    "direction": "in",
    "authLevel": "function"
},

Queste proprietà sono descritte nella sezione configuration.The configuration section explains these properties.

Ecco il codice script C# associato a un oggetto HttpRequestMessage:Here's C# script code that binds to HttpRequestMessage:

using System.Net;
using System.Threading.Tasks;

public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, TraceWriter log)
{
    log.Info($"C# HTTP trigger function processed a request. RequestUri={req.RequestUri}");

    // parse query parameter
    string name = req.GetQueryNameValuePairs()
        .FirstOrDefault(q => string.Compare(q.Key, "name", true) == 0)
        .Value;

    // Get request body
    dynamic data = await req.Content.ReadAsAsync<object>();

    // Set name to query string or body data
    name = name ?? data?.name;

    return name == null
        ? req.CreateResponse(HttpStatusCode.BadRequest, "Please pass a name on the query string or in the request body")
        : req.CreateResponse(HttpStatusCode.OK, "Hello " + name);
}

È possibile associare a un oggetto personalizzato invece di HttpRequestMessage.You can bind to a custom object instead of HttpRequestMessage. Questo oggetto viene creato dal corpo della richiesta e analizzato come JSON.This object is created from the body of the request, parsed as JSON. Analogamente, un tipo può essere passato al binding di output della risposta HTTP e restituito come corpo della risposta, con un codice di stato 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;

public static string Run(CustomObject req, TraceWriter log)
{
    return "Hello " + req?.name;
}

public class CustomObject {
     public String name {get; set;}
}
}

Trigger - Esempio in F#Trigger - F# example

L'esempio seguente mostra un'associazione di trigger in un file function.json e una funzione F# che usa l'associazione.The following example shows a trigger binding in a function.json file and an F# function that uses the binding. La funzione cerca un parametro name nella stringa di query o nel corpo della richiesta HTTP.The function looks for a name parameter either in the query string or the body of the HTTP request.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

{
    "name": "req",
    "type": "httpTrigger",
    "direction": "in",
    "authLevel": "function"
},

Queste proprietà sono descritte nella sezione configuration.The configuration section explains these properties.

Ecco il codice 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

È necessario un file project.json che usa NuGet per fare riferimento agli assembly FSharp.Interop.Dynamic e Dynamitey, come illustrato nell'esempio seguente: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"
      }
    }
  }
}

Trigger - esempio JavaScriptTrigger - JavaScript example

L'esempio seguente illustra un'associazione di trigger in un file function.json e una funzione JavaScript che usa l'associazione.The following example shows a trigger binding in a function.json file and a JavaScript function that uses the binding. La funzione cerca un parametro name nella stringa di query o nel corpo della richiesta HTTP.The function looks for a name parameter either in the query string or the body of the HTTP request.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

{
    "name": "req",
    "type": "httpTrigger",
    "direction": "in",
    "authLevel": "function"
},

Queste proprietà sono descritte nella sezione configuration.The configuration section explains these properties.

Ecco il codice 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: 200, /* 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();
};

Trigger - esempio di webhookTrigger - webhook example

Vedere l'esempio specifico per ciascun linguaggio:See the language-specific example:

Webhook - esempio C#Webhook - C# example

Nell'esempio seguente un funzione c# che invia un HTTP 200 in risposta a una richiesta JSON generica.The following example shows a C# function that sends an HTTP 200 in response to a generic JSON request.

[FunctionName("HttpTriggerCSharp")]
public static HttpResponseMessage Run([HttpTrigger(AuthorizationLevel.Anonymous, WebHookType = "genericJson")] HttpRequestMessage req)
{
    return req.CreateResponse(HttpStatusCode.OK);
}

Webhook - esempio di script C#Webhook - C# script example

L'esempio seguente mostra un'associazione di trigger webhook in un file function.json e una funzione script C# che usa l'associazione.The following example shows a webhook trigger binding in a function.json file and a C# script function that uses the binding. Questa funzione registra i commenti sui problemi di GitHub.The function logs GitHub issue comments.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

{
    "webHookType": "github",
    "name": "req",
    "type": "httpTrigger",
    "direction": "in",
},

Queste proprietà sono descritte nella sezione configuration.The configuration section explains these properties.

Ecco il codice script C#:Here's the C# script code:

#r "Newtonsoft.Json"

using System;
using System.Net;
using System.Threading.Tasks;
using Newtonsoft.Json;

public static async Task<object> Run(HttpRequestMessage req, TraceWriter log)
{
    string jsonContent = await req.Content.ReadAsStringAsync();
    dynamic data = JsonConvert.DeserializeObject(jsonContent);

    log.Info($"WebHook was triggered! Comment: {data.comment.body}");

    return req.CreateResponse(HttpStatusCode.OK, new {
        body = $"New GitHub comment: {data.comment.body}"
    });
}

Webhook - esempio F#Webhook - F# example

L'esempio seguente mostra un'associazione di trigger webhook in un file function.json e una funzione F# che usa l'associazione.The following example shows a webhook trigger binding in a function.json file and an F# function that uses the binding. Questa funzione registra i commenti sui problemi di GitHub.The function logs GitHub issue comments.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

{
    "webHookType": "github",
    "name": "req",
    "type": "httpTrigger",
    "direction": "in",
},

Queste proprietà sono descritte nella sezione configuration.The configuration section explains these properties.

Ecco il codice F#:Here's the F# code:

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

type Response = {
    body: string
}

let Run(req: HttpRequestMessage, log: TraceWriter) =
    async {
        let! content = req.Content.ReadAsStringAsync() |> Async.AwaitTask
        let data = content |> JsonConvert.DeserializeObject
        log.Info(sprintf "GitHub WebHook triggered! %s" data?comment?body)
        return req.CreateResponse(
            HttpStatusCode.OK,
            { body = sprintf "New GitHub comment: %s" data?comment?body })
    } |> Async.StartAsTask

Webhook - esempio JavaScriptWebhook - JavaScript example

L'esempio seguente mostra un'associazione di trigger webhook in un file function.json e una funzione JavaScript che usa l'associazione.The following example shows a webhook trigger binding in a function.json file and a JavaScript function that uses the binding. Questa funzione registra i commenti sui problemi di GitHub.The function logs GitHub issue comments.

Ecco i dati di associazione nel file function.json:Here's the binding data in the function.json file:

{
    "webHookType": "github",
    "name": "req",
    "type": "httpTrigger",
    "direction": "in",
},

Queste proprietà sono descritte nella sezione configuration.The configuration section explains these properties.

Ecco il codice JavaScript:Here's the JavaScript code:

```

```javascript
module.exports = function (context, data) {
    context.log('GitHub WebHook triggered!', data.comment.body);
    context.res = { body: 'New GitHub comment: ' + data.comment.body };
    context.done();
};

Trigger - attributiTrigger - attributes

In librerie di classi c#, utilizzare il HttpTrigger attributo, definito nel pacchetto NuGet Microsoft.Azure.WebJobs.Extensions.Http.In C# class libraries, use the HttpTrigger attribute, defined in NuGet package Microsoft.Azure.WebJobs.Extensions.Http.

È possibile impostare il livello di autorizzazione e i metodi HTTP consentiti nei parametri di costruttore dell'attributo. Sono disponibili proprietà per il modello di route e il tipo di 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. Per altre informazioni su queste impostazioni, vedere Trigger - configurazione.For more information about these settings, see Trigger - configuration. Di seguito è mostrato un attributo HttpTrigger in una firma del metodo:Here's an HttpTrigger attribute in a method signature:

[FunctionName("HttpTriggerCSharp")]
public static HttpResponseMessage Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, WebHookType = "genericJson")] HttpRequestMessage req)
{
    ...
}

Per un esempio completo, vedere Trigger - esempio c#.For a complete example, see Trigger - C# example.

Trigger - configurazioneTrigger - configuration

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json e nell'attributo HttpTrigger.The following table explains the binding configuration properties that you set in the function.json file and the HttpTrigger attribute.

Proprietà di function.jsonfunction.json property Proprietà dell'attributoAttribute property DESCRIZIONEDescription
typetype n/dn/a Obbligatoria. Deve essere impostata su httpTrigger.Required - must be set to httpTrigger.
directiondirection n/dn/a Obbligatoria. Deve essere impostata su in.Required - must be set to in.
nomename n/dn/a Obbligatoria. Nome della variabile usato nel codice della funzione per la richiesta o il corpo della richiesta.Required - the variable name used in function code for the request or request body.
authLevelauthLevel AuthLevelAuthLevel Determina le eventuali chiavi che devono essere presenti nella richiesta per richiamare la funzione.Determines what keys, if any, need to be present on the request in order to invoke the function. Il livello di autorizzazione può corrispondere a uno dei valori seguenti:The authorization level can be one of the following values:
  • anonymous—Non è richiesta nessuna chiave API.anonymous—No API key is required.
  • function—È richiesta una chiave API specifica della funzione.function—A function-specific API key is required. Questo è il valore predefinito se non ne viene specificato nessuno.This is the default value if none is provided.
  • admin—È richiesta la chiave master.admin—The master key is required.
Per altre informazioni, consultare la sezione sulle chiavi di autorizzazione.For more information, see the section about authorization keys.
methodsmethods MetodiMethods Matrice di metodi HTTP a cui la funzione risponde.An array of the HTTP methods to which the function responds. Se non viene specificata, la funzione risponde a tutti i metodi HTTP.If not specified, the function responds to all HTTP methods. Vedere Personalizzare l'endpoint HTTP.See customize the http endpoint.
routeroute RouteRoute Definisce il modello di route, controllando a quali URL di richiesta risponde la funzione.Defines the route template, controlling to which request URLs your function responds. Il valore predefinito, se non ne viene specificato nessuno, è <functionname>.The default value if none is provided is <functionname>. Per altre informazioni, vedere Personalizza l'endpoint HTTP.For more information, see customize the http endpoint.
webHookTypewebHookType WebHookTypeWebHookType Configura il trigger HTTP perché funga da ricevitore webhook per il provider specificato.Configures the HTTP trigger to act as a webhook receiver for the specified provider. Non impostare la proprietà methods se si imposta questa proprietà.Don't set the methods property if you set this property. Il tipo di webhook può essere uno dei seguenti:The webhook type can be one of the following values:
  • genericJson—Endpoint di webhook per uso generico senza logica per un provider specifico.genericJson—A general-purpose webhook endpoint without logic for a specific provider. Questa impostazione limita le richieste solo a quelle che usano HTTP POST e con il tipo di contenuto application/json.This setting restricts requests to only those using HTTP POST and with the application/json content type.
  • github—La funzione risponde ai webhook GitHub.github—The function responds to GitHub webhooks. Non usare la proprietà authLevel con webhook GitHub.Do not use the authLevel property with GitHub webhooks. Per altre informazioni, vedere la sezione con relativa ai webhook GitHub più avanti in questo articolo.For more information, see the GitHub webhooks section later in this article.
  • slack—La funzione risponde ai webhook Slack.slack—The function responds to Slack webhooks. Non usare la proprietà authLevel con webhook Slack.Do not use the authLevel property with Slack webhooks. Per altre informazioni, vedere la sezione con relativa ai webhook Slack più avanti in questo articolo.For more information, see the Slack webhooks section later in this article.

Trigger - usoTrigger - usage

Per le funzioni C# e F#, è possibile dichiarare HttpRequestMessage o un tipo personalizzato come tipo dell'input del trigger.For C# and F# functions, you can declare the type of your trigger input to be either HttpRequestMessage or a custom type. Se si sceglie HttpRequestMessage, si ottiene accesso completo all'oggetto richiesta.If you choose HttpRequestMessage, you get full access to the request object. Per un tipo personalizzato, Funzioni cerca di analizzare il corpo della richiesta JSON per impostare le proprietà dell'oggetto.For a custom type, Functions tries to parse the JSON request body to set the object properties.

Per le funzioni JavaScript, il runtime di Funzioni fornisce il corpo della richiesta invece dell'oggetto richiesta.For JavaScript functions, the Functions runtime provides the request body instead of the request object. Per altre informazioni, vedere l'esempio di trigger JavaScript.For more information, see the JavaScript trigger example.

Webhook GitHubGitHub webhooks

Per rispondere ai webhook GitHub, creare prima di tutto la funzione con un trigger HTTP e impostare la proprietà webHookType su github.To respond to GitHub webhooks, first create your function with an HTTP Trigger, and set the webHookType property to github. Copiare quindi l'URL e la chiave API nella pagina Aggiungi webhook del repository GitHub.Then copy its URL and API key into the Add webhook page of your GitHub repository.

Per un esempio, vedere Creare una funzione attivata da un webhook GitHub.For an example, see Create a function triggered by a GitHub webhook.

Webhook SlackSlack webhooks

Il webhook Slack genera automaticamente un token invece di consentire di specificarlo, quindi è necessario configurare una chiave specifica della funzione con il token da 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. Vedere Chiavi di autorizzazione.See Authorization keys.

Personalizzare l'endpoint HTTPCustomize the HTTP endpoint

Per impostazione predefinita, quando si crea una funzione per un trigger HTTP o un webhook, la funzione può essere indirizzata con una route nel formato seguente:By default when you create a function for an HTTP trigger, or WebHook, the function is addressable with a route of the form:

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

È possibile personalizzare questa route tramite la proprietà route facoltativa nell'associazione di input del trigger HTTP.You can customize this route using the optional route property on the HTTP trigger's input binding. Ad esempio, il file function.json seguente definisce una proprietà route per un trigger 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"
    }
    ]
}

Con questa configurazione, la funzione può ora essere indirizzata con la route seguente invece che con quella originale.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

In questo modo il codice della funzione può supportare due parametri nell'indirizzo, category e id. I parametri sono compatibili con qualsiasi vincolo di route dell'API Web.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. Il codice di funzione C# seguente usa entrambi i parametri.The following C# function code makes use of both parameters.

public static Task<HttpResponseMessage> Run(HttpRequestMessage req, string category, int? id, 
                                                TraceWriter log)
{
    if (id == null)
        return  req.CreateResponse(HttpStatusCode.OK, $"All {category} items were requested.");
    else
        return  req.CreateResponse(HttpStatusCode.OK, $"{category} item with id = {id} has been requested.");
}

Di seguito è mostrato il codice di funzione Node.js che usa gli stessi parametri di route.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: 200, /* Defaults to 200 */
            body: "All " + category + " items were requested."
        };
    }
    else {
        context.res = {
            // status: 200, /* Defaults to 200 */
            body: category + " item with id = " + id + " was requested."
        };
    }

    context.done();
} 

Per impostazione predefinita, tutte le route di funzione sono precedute da api.By default, all function routes are prefixed with api. È inoltre possibile personalizzare o rimuovere il prefisso con la proprietà http.routePrefix nel file host.json.You can also customize or remove the prefix using the http.routePrefix property in your host.json file. Nell'esempio seguente viene rimosso il prefisso della route api usando una stringa vuota per il prefisso nel file 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": ""
    }
}

Chiavi di autorizzazioneAuthorization keys

I trigger HTTP consentono di usare le chiavi per una maggiore sicurezza.HTTP triggers let you use keys for added security. Un trigger HTTP standard può usare queste chiavi come chiave API, richiedendone la presenza nella richiesta.A standard HTTP trigger can use these as an API key, requiring the key to be present on the request. I webhook possono usare le chiavi per autorizzare le richieste in svariati modi, a seconda di ciò che il provider supporta.Webhooks can use keys to authorize requests in a variety of ways, depending on what the provider supports.

Le chiavi vengono archiviate come parte dell'app per le funzioni in Azure e crittografate inattive.Keys are stored as part of your function app in Azure and are encrypted at rest. Per visualizzare le chiavi, crearne di nuove o aggiornare le chiavi con nuovi valori, passare a una delle funzioni nel portale e selezionare "Gestisci".To view your keys, create new ones, or roll keys to new values, navigate to one of your functions in the portal and select "Manage."

Esistono due tipi di chiavi:There are two types of keys:

  • Chiavi host: queste chiavi vengono condivise da tutte le funzioni nell'app per le funzioni.Host keys: These keys are shared by all functions within the function app. Quando vengono usate come chiave API, consentono l'accesso a tutte le funzioni nell'app per le funzioni.When used as an API key, these allow access to any function within the function app.
  • Chiavi di funzione: queste chiavi si applicano solo alle funzioni specifiche sotto le quali vengono definite.Function keys: These keys apply only to the specific functions under which they are defined. Quando vengono usate come chiave API, consentono l'accesso solo a tale funzione.When used as an API key, these only allow access to that function.

Ogni chiave viene denominata per riferimento ed esiste una chiave predefinita (denominata "default") a livello di funzione e di host.Each key is named for reference, and there is a default key (named "default") at the function and host level. Le chiavi di funzione hanno la precedenza sulle chiavi host.Function keys take precedence over host keys. Se sono definite due chiavi con lo stesso nome, viene usata sempre la chiave di funzione.When two keys are defined with the same name, the function key is always used.

La chiave master è una chiave host predefinita denominata "_master", definita per ogni app per le funzioni.The master key is a default host key named "_master" that is defined for each function app. Questa chiave non può essere revocata.This key cannot be revoked. Fornisce l'accesso amministrativo alle API di runtime.It provides administrative access to the runtime APIs. Per usare "authLevel": "admin" nel file JSON di binding è necessario presentare questa chiave nella richiesta. Qualsiasi altra chiave provoca un errore di autorizzazione.Using "authLevel": "admin" in the binding JSON requires this key to be presented on the request; any other key results in authorization failure.

Importante

Date le autorizzazioni elevate concesse dalla chiave master, è consigliabile non condividere questa chiave con terze parti o distribuirla in applicazioni client native.Due to the elevated permissions granted by the master key, you should not share this key with third parties or distribute it in native client applications. Fare attenzione quando si sceglie il livello di autorizzazione di amministratore.Use caution when choosing the admin authorization level.

Autorizzazione della chiave APIAPI key authorization

Per impostazione predefinita, un trigger HTTP richiede una chiave API nella richiesta HTTP.By default, an HTTP trigger requires an API key in the HTTP request. La richiesta HTTP è quindi in genere simile alla seguente:So your HTTP request normally looks like the following:

https://<yourapp>.azurewebsites.net/api/<function>?code=<ApiKey>

La chiave può essere inclusa in una variabile della stringa di query denominata code, come sopra, oppure in un'intestazione HTTP x-functions-key.The key can be included in a query string variable named code, as above, or it can be included in an x-functions-key HTTP header. Il valore della chiave può essere una chiave di funzione definita per la funzione o una chiave host.The value of the key can be any function key defined for the function, or any host key.

È possibile consentire le richieste anonime, che non richiedono chiavi.You can allow anonymous requests, which do not require keys. È anche possibile richiedere l'uso della chiave master.You can also require that the master key be used. Per modificare il livello di autorizzazione predefinito, usare la proprietà authLevel nel file JSON di binding.You change the default authorization level by using the authLevel property in the binding JSON. Per altre informazioni, vedere Trigger - configurazioneFor more information, see Trigger - configuration.

Chiavi e webhookKeys and webhooks

L'autorizzazione webhook viene gestita dal componente ricevitore dei webhook, che fa parte del trigger HTTP, e il meccanismo varia in base al tipo di webhook.Webhook authorization is handled by the webhook receiver component, part of the HTTP trigger, and the mechanism varies based on the webhook type. Ogni meccanismo tuttavia si basa su una chiave.Each mechanism does, however rely on a key. Per impostazione predefinita, viene usata la chiave di funzione denominata "default".By default, the function key named "default" is used. Per usare una chiave diversa, configurare il provider di webhook per inviare il nome della chiave con la richiesta in uno dei modi seguenti:To use a different key, configure the webhook provider to send the key name with the request in one of the following ways:

  • Stringa di query: il provider passa il nome della chiave nel parametro della stringa di query clientid, ad esempio https://<yourapp>.azurewebsites.net/api/<funcname>?clientid=<keyname>.Query string: The provider passes the key name in the clientid query string parameter, such as https://<yourapp>.azurewebsites.net/api/<funcname>?clientid=<keyname>.
  • Intestazione della richiesta: il provider passa il nome della chiave nell'intestazione x-functions-clientid.Request header: The provider passes the key name in the x-functions-clientid header.

Trigger - proprietà di host.jsonTrigger - host.json properties

Il file host.json contiene le impostazioni che controllano il comportamento del trigger HTTP.The host.json file contains settings that control HTTP trigger behavior.

{
    "http": {
        "routePrefix": "api",
        "maxOutstandingRequests": 20,
        "maxConcurrentRequests": 10,
        "dynamicThrottlesEnabled": false
    }
}
ProprietàProperty DefaultDefault DescrizioneDescription
routePrefixroutePrefix apiapi Il prefisso della route che si applica a tutte le route.The route prefix that applies to all routes. Utilizzare una stringa vuota per rimuovere il prefisso predefinito.Use an empty string to remove the default prefix.
maxOutstandingRequestsmaxOutstandingRequests -1-1 Il numero massimo di richieste in sospeso che verrà mantenuto in un determinato intervallo.The maximum number of outstanding requests that are held at any given time. Questo limite include le richieste che vengono messe in coda ma non hanno avviato l'esecuzione, nonché le esecuzioni in corso.This limit includes requests that are queued but have not started executing, as well as any in progress executions. Le richieste in arrivo che superano questo limite vengono rifiutate con la risposta 429 "Occupato".Any incoming requests over this limit are rejected with a 429 "Too Busy" response. Ciò consente ai chiamanti di usare strategie di ripetizione dei tentativi basate sul tempo e di controllare la latenza massima delle richieste.That allows callers to employ time-based retry strategies, and also helps you to control maximum request latencies. Questa impostazione controlla solo l'accodamento che si verifica all'interno del percorso di esecuzione dell'host dello script.This only controls queuing that occurs within the script host execution path. Altre code, ad esempio la coda di richieste ASP.NET, saranno valide e non interessate da questa impostazione.Other queues such as the ASP.NET request queue will still be in effect and unaffected by this setting. Il valore predefinito è unbounded.The default is unbounded.
maxConcurrentRequestsmaxConcurrentRequests -1-1 Il numero massimo di funzioni HTTP che verrà eseguito in parallelo.The maximum number of http functions that will be executed in parallel. Ciò consente di controllare la concorrenza e pertanto di semplificare la gestione dell'uso delle risorse.This allows you to control concurrency, which can help manage resource utilization. Ad esempio, potrebbe essere presente una funzione HTTP che usa una quantità di risorse di sistema (memoria/CPU/socket) tale da creare problemi quando la concorrenza è troppo elevata.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. Oppure potrebbe essere presente una funzione che invia richieste a un servizio di terze parti e tali chiamate devono essere a frequenza limitata.Or you might have a function that makes outbound requests to a third party service, and those calls need to be rate limited. In questi casi potrebbe risultare utile l'applicazione di una limitazione.In these cases, applying a throttle here can help. Il valore predefinito è unbounded.The default is unbounded.
dynamicThrottlesEnableddynamicThrottlesEnabled falsefalse Quando è abilitata, questa impostazione determina la pipeline di elaborazione della richiesta per il controllo periodico delle prestazioni dei contatori del sistema, ad esempio connessioni/thread/processi/memoria/CPU e così via. Se uno di questi contatori supera una soglia massima predefinita (80%), le richieste verranno rifiutate con una risposta 429 "Occupato" fino a quando i contatori non tornano a livelli normali.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.

OutputOutput

Usare l'associazione di output HTTP per rispondere al mittente della richiesta HTTP.Use the HTTP output binding to respond to the HTTP request sender. Questa associazione richiede un trigger HTTP e consente di personalizzare la risposta associata alla richiesta del trigger.This binding requires an HTTP trigger and allows you to customize the response associated with the trigger's request. Se non viene specificato un binding di output HTTP, un trigger HTTP restituisce HTTP 200 OK con un corpo vuoto.If an HTTP output binding is not provided, an HTTP trigger returns HTTP 200 OK with an empty body.

Output - configurazioneOutput - configuration

C# delle librerie di classe, non sono disponibili proprietà di configurazione di associazione output specifici.For C# class libraries, there are no output-specific binding configuration properties. Per inviare una risposta HTTP, impostare il tipo restituito della funzione su HttpResponseMessage o Task<HttpResponseMessage>.To send an HTTP response, make the function return type HttpResponseMessage or Task<HttpResponseMessage>.

Per gli altri linguaggi un binding di output HTTP è definito come un oggetto JSON nella matrice bindings di function.json, come illustrato nell'esempio seguente:For other languages, an HTTP output binding is defined as a JSON object in the bindings array of function.json, as shown in the following example:

{
    "name": "res",
    "type": "http",
    "direction": "out"
}

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json.The following table explains the binding configuration properties that you set in the function.json file.

ProprietàProperty DESCRIZIONEDescription
typetype Il valore deve essere impostato su http.Must be set to http.
directiondirection Il valore deve essere impostato su out.Must be set to out.
nomename Nome della variabile usato nel codice della funzione per la risposta.The variable name used in function code for the response.

Output - usoOutput - usage

È possibile usare il parametro di output per rispondere al chiamante HTTP o webhook.You can use the output parameter to respond to the HTTP or webhook caller. È anche possibile usare modelli di risposta standard del linguaggio.You can also use the language-standard response patterns. Per altre risposte di esempio, vedere l'esempio di trigger e l'esempio di webhook.For example responses, see the trigger example and the webhook example.

Passaggi successiviNext steps