Trigger HTTP di Funzioni di Azure

  • Articolo

Un trigger HTTP consente di richiamare una funzione con una richiesta HTTP e può essere usato per compilare API senza server e rispondere ai webhook.

Il valore restituito predefinito per una funzione attivata tramite HTTP è:

  • HTTP 204 No Content con un corpo vuoto in Funzioni 2.x e versioni successive
  • HTTP 200 OK con un corpo vuoto in Funzioni 1.x

Per modificare la risposta HTTP, configurare un'associazione di output.

Per ulteriori informazioni sulle associazioni HTTP, vedere la panoramica e i riferimenti all’associazione di output.

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. Per altre informazioni, vedere How to manage connections in Azure Functions (Come gestire le connessioni in Funzioni di Azure).

Importante

Questo articolo usa schede per supportare più versioni del modello di programmazione Node.js. Il modello v4 è disponibile a livello generale ed è progettato per offrire un'esperienza più flessibile e intuitiva per gli sviluppatori JavaScript e TypeScript. Per altre informazioni sul funzionamento del modello v4, vedere la guida per sviluppatori di Funzioni di Azure Node.js. Per altre informazioni sulle differenze tra v3 e v4, vedere la guida alla migrazione.

Funzioni di Azure supporta due modelli di programmazione per Python. Il modo in cui si definiscono le associazioni dipende dal modello di programmazione scelto.

Il modello di programmazione Python v2 consente di definire associazioni usando elementi Decorator direttamente nel codice della funzione Python. Per altre informazioni, vedere la Guida per sviluppatori Python.

Questo articolo supporta entrambi i modelli di programmazione.

Esempio

È possibile creare una funzione C# usando una delle modalità C# seguenti:

  • Modello di lavoro isolato: funzione C# compilata eseguita in un processo di lavoro isolato dal runtime. Il processo di lavoro isolato è necessario per supportare le funzioni C# in esecuzione in LTS e versioni non LTS .NET e .NET Framework. Le estensioni per le funzioni del processo di lavoro isolato usano Microsoft.Azure.Functions.Worker.Extensions.* spazi dei nomi.
  • Modello in-process: funzione C# compilata eseguita nello stesso processo del runtime di Funzioni. In una variante di questo modello, le funzioni possono essere eseguite usando script C#, che è supportato principalmente per la modifica del portale C#. Le estensioni per le funzioni in-process usano Microsoft.Azure.WebJobs.Extensions.* spazi dei nomi.

Importante

Il supporto terminerà per il modello in-process il 10 novembre 2026. È consigliabile eseguire la migrazione delle app al modello di lavoro isolato per il supporto completo.

Il codice in questo articolo usa per impostazione predefinita la sintassi .NET Core, usata in Funzioni versione 2.x e successive. Per informazioni sulla sintassi 1.x, consultare i modelli delle funzioni 1.x.

L'esempio seguente mostra un trigger HTTP che restituisce una risposta "hello, world" come IActionResult, usando l'integrazione di ASP.NET Core in .NET Isolated:

[Function("HttpFunction")]
public IActionResult Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req)
{
    return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
}

L'esempio seguente mostra un trigger HTTP che restituisce una risposta "hello world" come oggetto HttpResponseData :

[Function(nameof(HttpFunction))]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger(nameof(HttpFunction));
    logger.LogInformation("message logged");

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString("Welcome to .NET isolated worker !!");

    return response;
}

Questa sezione contiene gli esempi seguenti:

Gli esempi riportati di seguito illustrano l’associazione con trigger HTTP.

Leggere un parametro dalla stringa di query

Questo esempio legge un parametro, denominato id, dalla stringa di query e lo usa per creare un documento JSON restituito al client, con tipo di contenuto 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();
    }
}

Leggere il corpo da una richiesta POST

Questo esempio legge il corpo di una richiesta POST, come String, e lo usa per creare un documento JSON restituito al client, con tipo di contenuto 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();
        }
    }

Leggere un parametro da una route

Questo esempio legge un parametro obbligatorio, denominato id, e un parametro facoltativo name dal percorso della route e usa tali parametri per creare un documento JSON restituito al client, con tipo di contenuto application/json.

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

Leggere il corpo POJO da una richiesta POST

Ecco il codice per la classe ToDoItem a cui si fa riferimento in questo esempio:


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 + "}";
  }
}

Questo esempio legge il corpo di una richiesta POST. Il corpo della richiesta viene automaticamente deserializzato in un oggetto ToDoItem e viene restituito al client, con tipo di contenuto application/json. Il parametro ToDoItem viene serializzato dal runtime di Funzioni poiché è assegnato alla proprietà body della classe HttpMessageResponse.Builder.

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

L'esempio seguente mostra una funzione TypeScript trigger HTTP. La funzione cerca un parametro name nella stringa di query o nel corpo della richiesta HTTP.

import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    context.log(`Http function processed request for url "${request.url}"`);

    const name = request.query.get('name') || (await request.text()) || 'world';

    return { body: `Hello, ${name}!` };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: httpTrigger1,
});

L'esempio seguente mostra una funzione JavaScript trigger HTTP. La funzione cerca un parametro name nella stringa di query o nel corpo della richiesta HTTP.

const { app } = require('@azure/functions');

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        context.log(`Http function processed request for url "${request.url}"`);

        const name = request.query.get('name') || (await request.text()) || 'world';

        return { body: `Hello, ${name}!` };
    },
});

L'esempio seguente mostra un'associazione di trigger in un file function.json e una funzione di PowerShell. La funzione cerca un parametro name nella stringa di query o nel corpo della richiesta HTTP.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$name = $Request.Query.Name
if (-not $name) {
    $name = $Request.Body.Name
}

$body = "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."

if ($name) {
    $body = "Hello, $name. This HTTP triggered function executed successfully."
}

# Associate values to output bindings by calling 'Push-OutputBinding'.
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [HttpStatusCode]::OK
    Body       = $body
})

L'esempio seguente mostra un'associazione di trigger e una funzione Python che usa l'associazione. La funzione cerca un parametro name nella stringa di query o nel corpo della richiesta HTTP. L'esempio dipende dal fatto che si usi il modello di programmazione Python v1 o v2.

import azure.functions as func
import logging

app = func.FunctionApp()

@app.function_name(name="HttpTrigger1")
@app.route(route="hello", auth_level=func.AuthLevel.ANONYMOUS)
def test_function(req: func.HttpRequest) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request.')
    return func.HttpResponse(
        "This HTTP triggered function executed successfully.",
        status_code=200
        )

Attributi

Sia le librerie C# in-process che il processo di lavoro isolato usano HttpTriggerAttribute per definire l'associazione di trigger. Lo script C# usa invece un file di configurazione function.json come descritto nella guida per gli script C#.

Nelle app per le funzioni del processo di lavoro isolato supporta HttpTriggerAttribute i parametri seguenti:

Parametri Descrizione
AuthLevel Determina le eventuali chiavi che devono essere presenti nella richiesta per richiamare la funzione. Per i valori supportati, vedere Livello di autorizzazione.
Metodi Matrice di metodi HTTP a cui la funzione risponde. Se non viene specificata, la funzione risponde a tutti i metodi HTTP. Vedere Personalizzare l'endpoint HTTP.
Itinerario Definisce il modello di route, controllando a quali URL di richiesta risponde la funzione. Il valore predefinito, se non ne viene specificato nessuno, è <functionname>. Per altre informazioni, vedere Personalizzare l'endpoint HTTP.

Elementi Decorator

Si applica solo al modello di programmazione Python v2.

Per le funzioni Python v2 definite usando un elemento Decorator, le proprietà seguenti per un trigger sono definite nell'elemento Decorator, che aggiunge l'associazione route HttpTrigger e HttpOutput:

Proprietà Descrizione
route Route per l'endpoint HTTP. Se None, verrà impostato sul nome della funzione se presente o il nome della funzione Python definito dall'utente.
trigger_arg_name Nome dell'argomento per HttpRequest. Il valore predefinito è 'req'.
binding_arg_name Nome dell'argomento per HttpResponse. Il valore predefinito è '$return'.
methods Tupla dei metodi HTTP a cui risponde la funzione.
auth_level Determina le eventuali chiavi che devono essere presenti nella richiesta per richiamare la funzione.

Per le funzioni Python definite tramite function.json, vedere la sezione Configurazione .

Annotazioni

Nella libreria di runtime delle funzioni Java usare l'annotazione HttpTrigger, che supporta le impostazioni seguenti:

Impostazione

Si applica solo al modello di programmazione Python v1.

Nella tabella seguente vengono illustrate le proprietà che è possibile impostare sull'oggetto options passato al app.http() metodo .

Proprietà Descrizione
authLevel Determina le eventuali chiavi che devono essere presenti nella richiesta per richiamare la funzione. Per i valori supportati, vedere Livello di autorizzazione.
methods Matrice di metodi HTTP a cui la funzione risponde. Se non viene specificata, la funzione risponde a tutti i metodi HTTP. Vedere Personalizzare l'endpoint HTTP.
route Definisce il modello di route, controllando a quali URL di richiesta risponde la funzione. Il valore predefinito, se non ne viene specificato nessuno, è <functionname>. Per altre informazioni, vedere Personalizzare l'endpoint HTTP.

La tabella seguente illustra le proprietà di configurazione del trigger impostate nel file function.json, che differisce dalla versione di runtime.

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json.

Proprietà di function.json Descrizione
type Obbligatoria. Deve essere impostata su httpTrigger.
direction Obbligatoria. Deve essere impostata su in.
name Obbligatoria. Nome della variabile usato nel codice della funzione per la richiesta o il corpo della richiesta.
authLevel Determina le eventuali chiavi che devono essere presenti nella richiesta per richiamare la funzione. Per i valori supportati, vedere Livello di autorizzazione.
methods Matrice di metodi HTTP a cui la funzione risponde. Se non viene specificata, la funzione risponde a tutti i metodi HTTP. Vedere Personalizzare l'endpoint HTTP.
route Definisce il modello di route, controllando a quali URL di richiesta risponde la funzione. Il valore predefinito, se non ne viene specificato nessuno, è <functionname>. Per altre informazioni, vedere Personalizzare l'endpoint HTTP.

Utilizzo

Questa sezione descrive in dettaglio come configurare l'associazione di funzioni del trigger HTTP.

L'annotazione HttpTrigger deve essere applicata a un parametro del metodo di uno dei tipi seguenti:

  • HttpRequestMessage<T>.
  • Qualsiasi tipo Java nativo, ad esempio int, String, byte[].
  • Valori nullable usando Facoltativo.
  • Qualsiasi tipo di oggetto Java normale (POJO).

Payload

Il tipo di input del trigger viene dichiarato come uno dei tipi seguenti:

Tipo Descrizione
HttpRequest L'uso di questo tipo richiede che l'app sia configurata con l'integrazione di ASP.NET Core in .NET Isolated.
In questo modo è possibile accedere completamente all'oggetto richiesta e all'oggetto HttpContext complessivo.
HttpRequestData Proiezione dell'oggetto richiesta.
Tipo personalizzato Quando il corpo della richiesta è JSON, il runtime tenterà di analizzarlo per impostare le proprietà dell'oggetto.

Quando il parametro trigger è un HttpRequestDataHttpRequest, i tipi personalizzati possono anche essere associati a parametri aggiuntivi usando Microsoft.Azure.Functions.Worker.Http.FromBodyAttribute. L'uso di questo attributo richiede Microsoft.Azure.Functions.Worker.Extensions.Http la versione 3.1.0 o successiva. Si noti che si tratta di un tipo diverso rispetto all'attributo simile in Microsoft.AspNetCore.Mvce quando si usa l'integrazione di ASP.NET Core, è necessario un riferimento completo o using un'istruzione. L'esempio seguente illustra come usare l'attributo per ottenere solo il contenuto del corpo pur avendo ancora accesso all'intero HttpRequest, usando l'integrazione di ASP.NET Core:

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using FromBodyAttribute = Microsoft.Azure.Functions.Worker.Http.FromBodyAttribute;

namespace AspNetIntegration
{
    public class BodyBindingHttpTrigger
    {
        [Function(nameof(BodyBindingHttpTrigger))]
        public IActionResult Run([HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req,
            [FromBody] Person person)
        {
            return new OkObjectResult(person);
        }
    }

    public record Person(string Name, int Age);
}

Personalizzare l'endpoint HTTP

Per impostazione predefinita, quando si crea una funzione per un trigger HTTP la funzione può essere indirizzata con una route nel formato seguente:

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

È possibile personalizzare questa route tramite la proprietà route facoltativa nell'associazione di input del trigger HTTP. I parametri sono compatibili con qualsiasi vincolo di route dell'API Web.

Il codice della funzione seguente accetta due parametri category e id nella route e scrive una risposta usando entrambi i parametri.

[Function("HttpTrigger1")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Function, "get", "post",
Route = "products/{category:alpha}/{id:int?}")] HttpRequestData req, string category, int? id,
FunctionContext executionContext)
{
    var logger = executionContext.GetLogger("HttpTrigger1");
    logger.LogInformation("C# HTTP trigger function processed a request.");

    var message = String.Format($"Category: {category}, ID: {id}");
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString(message);

    return response;
}

I parametri di route vengono definiti usando l'impostazione route dell'annotazione HttpTrigger . Il codice della funzione seguente accetta due parametri category e id nella route e scrive una risposta usando entrambi i parametri.

package com.function;

import java.util.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

public class HttpTriggerJava {
    public HttpResponseMessage<String> HttpTrigger(
            @HttpTrigger(name = "req",
                         methods = {"get"},
                         authLevel = AuthorizationLevel.FUNCTION,
                         route = "products/{category:alpha}/{id:int}") HttpRequestMessage<String> request,
            @BindingName("category") String category,
            @BindingName("id") int id,
            final ExecutionContext context) {

        String message = String.format("Category  %s, ID: %d", category, id);
        return request.createResponseBuilder(HttpStatus.OK).body(message).build();
    }
}

Ad esempio, il codice TypeScript seguente definisce una route proprietà per un trigger HTTP con due parametri e categoryid. Nell'esempio vengono letti i parametri dalla richiesta e vengono restituiti i relativi valori nella risposta.

import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const category = request.params.category;
    const id = request.params.id;

    return { body: `Category: ${category}, ID: ${id}` };
}

app.http('httpTrigger1', {
    methods: ['GET'],
    authLevel: 'anonymous',
    route: 'products/{category:alpha}/{id:int?}',
    handler: httpTrigger1,
});

Ad esempio, il codice JavaScript seguente definisce una route proprietà per un trigger HTTP con due parametri e categoryid. Nell'esempio vengono letti i parametri dalla richiesta e vengono restituiti i relativi valori nella risposta.

const { app } = require('@azure/functions');

app.http('httpTrigger1', {
    methods: ['GET'],
    authLevel: 'anonymous',
    route: 'products/{category:alpha}/{id:int?}',
    handler: async (request, context) => {
        const category = request.params.category;
        const id = request.params.id;

        return { body: `Category: ${category}, ID: ${id}` };
    },
});

Ad esempio, il codice seguente definisce una route proprietà per un trigger HTTP con due parametri e categoryid:

@app.function_name(name="httpTrigger")
@app.route(route="products/{category:alpha}/{id:int?}")

I parametri di route dichiarati nel file function.json sono accessibili come proprietà dell'oggetto $Request.Params .

$Category = $Request.Params.category
$Id = $Request.Params.id

$Message = "Category:" + $Category + ", ID: " + $Id

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [HttpStatusCode]::OK
    Body = $Message
})

Il contesto di esecuzione della funzione viene esposto tramite un parametro dichiarato come func.HttpRequest. Questa istanza consente a una funzione di accedere ai parametri di route di dati, ai valori della stringa di query e ai metodi che consentono di restituire le risposte HTTP.

Dopo che sono stati definiti, i parametri di route sono disponibili alla funzione tramite chiamata al metodo route_params.

import logging

import azure.functions as func

def main(req: func.HttpRequest) -> func.HttpResponse:

    category = req.route_params.get('category')
    id = req.route_params.get('id')
    message = f"Category: {category}, ID: {id}"

    return func.HttpResponse(message)

Con questa configurazione, la funzione può ora essere indirizzata con la route seguente invece che con quella originale.

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

Questa configurazione consente al codice della funzione di supportare due parametri nell'indirizzo, nella categoria e nell'ID. Per altre informazioni su come i parametri di route vengono tokenizzati in un URL, vedere Routing in ASP.NET Core.

Per impostazione predefinita, tutte le route di funzione sono precedute da api. È inoltre possibile personalizzare o rimuovere il prefisso con la proprietà extensions.http.routePrefix nel file host.json. Nell'esempio seguente viene rimosso il prefisso della route api usando una stringa vuota per il prefisso nel file host.json.

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

Uso dei parametri di route

I parametri di route che definiscono il modello di route di una funzione sono disponibili per ogni associazione. Se, ad esempio, è presente una route definita come "route": "products/{id}", un'associazione di archiviazione tabelle può usare il valore del parametro {id} nella configurazione dell'associazione.

La configurazione seguente illustra in che modo il parametro {id} viene passato a rowKey dell'associazione.

@app.table_input(arg_name="product", table_name="products", 
                 row_key="{id}", partition_key="products",
                 connection="AzureWebJobsStorage")

import { app, HttpRequest, HttpResponseInit, input, InvocationContext } from '@azure/functions';

const tableInput = input.table({
    connection: 'MyStorageConnectionAppSetting',
    partitionKey: 'products',
    tableName: 'products',
    rowKey: '{id}',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    return { jsonBody: context.extraInputs.get(tableInput) };
}

app.http('httpTrigger1', {
    methods: ['GET'],
    authLevel: 'anonymous',
    route: 'products/{id}',
    extraInputs: [tableInput],
    handler: httpTrigger1,
});

const { app, input } = require('@azure/functions');

const tableInput = input.table({
    connection: 'MyStorageConnectionAppSetting',
    partitionKey: 'products',
    tableName: 'products',
    rowKey: '{id}',
});

app.http('httpTrigger1', {
    methods: ['GET'],
    authLevel: 'anonymous',
    route: 'products/{id}',
    extraInputs: [tableInput],
    handler: async (request, context) => {
        return { jsonBody: context.extraInputs.get(tableInput) };
    },
});

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

Quando si usano parametri di route, viene creato automaticamente un oggetto invoke_URL_template per la funzione. I client possono usare il modello di URL per comprendere i parametri necessari per passare l'URL quando si chiama la funzione usando il relativo URL. Passare a una delle funzioni attivate da HTTP nella portale di Azure e selezionare Recupera URL funzione.

È possibile accedere a invoke_URL_template livello di codice usando le API di Azure Resource Manager per List Functions o Get Function.

Flussi HTTP (anteprima)

È ora possibile trasmettere le richieste e le risposte dall'endpoint HTTP nelle app per le funzioni Node.js v4. Per altre informazioni, vedere Flussi HTTP.

Utilizzo delle identità client

Se l'app per le funzioni usa l'autenticazione/autorizzazione di Servizio app , è possibile visualizzare informazioni sui client autenticati dal codice. Queste informazioni sono disponibili come intestazioni delle richieste inserite dalla piattaforma.

È anche possibile leggere queste informazioni dai dati di binding. Questa funzionalità è disponibile solo per il runtime di Funzioni 2.x e versioni successive. È anche al momento disponibile solo per i linguaggi .NET.

Le informazioni relative ai client autenticati sono disponibili come ClaimsPrincipal, disponibile come parte del contesto della richiesta, come illustrato nell'esempio seguente:

L'utente autenticato è disponibile tramite Intestazioni HTTP.

L'utente autenticato è disponibile tramite Intestazioni HTTP.

Livello di autorizzazione

Il livello di autorizzazione è un valore stringa che indica il tipo di chiave di autorizzazione necessaria per accedere all'endpoint della funzione. Per una funzione attivata da HTTP, il livello di autorizzazione può essere uno dei valori seguenti:

Valore del livello Descrizione
Anonimo Non è richiesta nessuna chiave API. Questo è il valore predefinito quando un livello non è impostato in modo specifico.
function È richiesta una chiave API specifica della funzione.
admin È richiesta la chiave master.
Valore del livello Descrizione
Anonimo Non è richiesta nessuna chiave API.
function È richiesta una chiave API specifica della funzione. Questo è il valore predefinito quando un livello non è impostato in modo specifico.
admin È richiesta la chiave master.

Chiavi di accesso alle funzioni

Funzioni consente di usare in fase di sviluppo le chiavi che rendono più difficile accedere agli endpoint di funzione HTTP. A meno che il livello di accesso HTTP in una funzione attivata tramite HTTP non sia impostato su anonymous, le richieste devono includere una chiave di accesso all'API.

Sebbene le chiavi forniscano un meccanismo di sicurezza predefinito, è consigliabile prendere in considerazione altre opzioni per proteggere un endpoint HTTP nell'ambiente di produzione. Ad esempio, non è consigliabile distribuire il segreto condiviso nelle app pubbliche. Se la funzione viene chiamata da un client pubblico, è consigliabile prendere in considerazione l'implementazione di un altro meccanismo di sicurezza. Per altre informazioni, vedere Proteggere un endpoint HTTP nell'ambiente di produzione.

Quando si rinnovano i valori della chiave di funzione, è necessario ridistribuire manualmente i valori di chiave aggiornati a tutti i client che chiamano la funzione.

Ambiti di autorizzazione (a livello di funzione)

Sono disponibili due ambiti dell'accesso per le chiavi a livello di funzione:

  • Funzione: queste chiavi si applicano solo alle funzioni specifiche in cui sono definite. Quando vengono usate come chiave API, consentono l'accesso solo a tale funzione.

  • Host: le chiavi con un ambito host possono essere usate per accedere a tutte le funzioni all'interno dell'app per le funzioni. Quando vengono usate come chiave API, consentono l'accesso a tutte le funzioni nell'app per le funzioni.

Ogni chiave viene denominata per riferimento ed è presente una chiave predefinita (denominata "default") a livello di funzione e host. Le chiavi di funzione hanno la precedenza sulle chiavi host. Se sono definite due chiavi con lo stesso nome, viene usata sempre la chiave di funzione.

Chiave master (a livello di amministratore)

Ogni app per le funzioni dispone anche di una chiave host a livello di amministratore denominata _master. Oltre a fornire l'accesso a livello di host a tutte le funzioni nell'app, la chiave master offre anche l'accesso amministrativo alle API REST di runtime. Questa chiave non può essere revocata. Quando si imposta un livello di accesso admin, le richieste devono usare la chiave master. Qualsiasi altra chiave provoca un errore di accesso.

Attenzione

A causa delle autorizzazioni elevate nell'app per le funzioni concesse dalla chiave master, non è consigliabile condividere questa chiave con terze parti o distribuirla nelle applicazioni client native. Fare attenzione quando si sceglie il livello di accesso di amministratore.

Ottenere le chiavi

Le chiavi vengono archiviate come parte dell'app per le funzioni in Azure e crittografate inattive. Per visualizzare le chiavi, crearne di nuove o eseguire il rollback delle chiavi ai nuovi valori, passare a una delle funzioni attivate da HTTP nella portale di Azure e selezionare Chiavi funzione.

È anche possibile gestire le chiavi host. Passare all'app per le funzioni nel portale di Azure e selezionare Chiavi dell'app.

È possibile ottenere chiavi di funzione e host a livello di codice usando le API di Azure Resource Manager. Sono disponibili API per elencare le chiavi di funzione e elencare le chiavi host e quando si usano gli slot di distribuzione, le API equivalenti sono slot list function keys slot e list host keys slot.

È anche possibile creare nuove chiavi di funzione e host a livello di codice usando le API Create Or Update Function Secret , Create Or Update Function Secret Slot, Create Or Update Host Secret e Create Or Update Host Secret Slot.

Le chiavi di funzione e host possono essere eliminate a livello di codice usando le API Elimina segreto funzione, Elimina slot segreto funzione, Elimina segreto host ed Elimina slot segreto host.

È anche possibile usare le API di gestione delle chiavi legacy per ottenere le chiavi di funzione, ma è consigliabile usare le API di Azure Resource Manager.

Autorizzazione della chiave API

La maggior parte dei modelli di trigger HTTP richiedono una chiave API nella richiesta. La richiesta HTTP è quindi in genere simile al seguente URL:

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

La chiave può essere inclusa in una variabile della stringa di query denominata code, come sopra. Può anche essere inclusa in un'intestazione HTTP x-functions-key. Il valore della chiave può essere una chiave di funzione definita per la funzione o una chiave host.

È possibile consentire le richieste anonime, che non richiedono chiavi. È anche possibile richiedere l'uso della chiave master. Per modificare il livello di autorizzazione predefinito, usare la proprietà authLevel nel file JSON di binding. Per altre informazioni, vedere Trigger - configurazione

Nota

Quando si eseguono funzioni localmente, l'autorizzazione viene disabilitata indipendentemente dall'impostazione del livello di autorizzazione specificata. Dopo la pubblicazione in Azure, viene applicata l'impostazione authLevel del trigger. Le chiavi sono comunque necessarie durante l’esecuzione in locale in un contenitore.

Proteggere un endpoint HTTP nell'ambiente di produzione

Per proteggere completamente gli endpoint di funzione nell'ambiente di produzione, è consigliabile implementare una delle opzioni di sicurezza a livello di app per le funzioni seguenti. Quando si usa uno di questi metodi di sicurezza a livello di app per le funzioni, è necessario impostare il livello di autorizzazione delle funzioni attivate da HTTP su anonymous.

Abilitare l'autenticazione/autorizzazione di Servizio app di Azure

La piattaforma servizio app consente di usare Microsoft Entra ID e diversi provider di identità di terze parti per autenticare i client. È possibile usare questa strategia per implementare regole di autorizzazione personalizzate per le funzioni ed è possibile lavorare con le informazioni utente dal codice di funzione. Per altre informazioni, vedere Autenticazione e autorizzazione in Servizio app di Azure e Utilizzo delle identità client.

Usare Gestione API di Azure (APIM) per autenticare le richieste

APIM offre un'ampia gamma di opzioni di sicurezza di API per le richieste in ingresso. Per altre informazioni, vedere Criteri di autenticazione di Gestione API di Azure. Con APIM, è possibile configurare l'app per le funzioni in modo che accetti le richieste solo dall'indirizzo IP dell'istanza APIM. Per altre informazioni, vedere Restrizioni degli indirizzi IP.

Distribuire l'app per le funzioni in isolamento

L'ambiente del servizio app di Azure offre un ambiente di hosting dedicato in cui eseguire le funzioni. L'ASE consente di configurare un singolo gateway front-end che è possibile usare per autenticare tutte le richieste in ingresso. Per altre informazioni, vedere Configurazione di un web application firewall (WAF) per l'ambiente del servizio app.

Webhooks

Nota

La modalità webhook è disponibile solo per il runtime di funzioni versione 1.x. Questa modifica è stata apportata per migliorare le prestazioni dei trigger HTTP nella versione 2.x e successive.

Nella versione 1.x, i modelli webhook forniscono una convalida aggiuntiva per i payload di webhook. Nella versione 2.x e successive, il trigger HTTP di base è ancora funzionante ed è l'approccio consigliato per i webhook.

Tipo di webhook

La webHookType proprietà di associazione indica il tipo se il webhook supportato dalla funzione , che determina anche il payload supportato. Il tipo di webhook può essere uno dei seguenti:

Valore del tipo Descrizione
genericJson Endpoint di webhook per uso generico senza logica per un provider specifico. Questa impostazione limita le richieste solo a quelle che usano HTTP POST e con il tipo di contenuto application/json.
github La funzione risponde ai webhook GitHub. Non usare la authLevel proprietà con webhook GitHub.
slack La funzione risponde ai webhook Slack. Non usare la authLevel proprietà con webhook Slack.

Quando si imposta la webHookType proprietà , non impostare anche la methods proprietà sull'associazione.

GitHub webhooks (Webhook GitHub)

Per rispondere ai webhook GitHub, creare prima di tutto la funzione con un trigger HTTP e impostare la proprietà webHookType su github. Copiare quindi l'URL e la chiave API nella pagina Aggiungi webhook del repository GitHub.

Screenshot che mostra come aggiungere un webhook per la funzione.

Webhook Slack

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. Vedere Chiavi di autorizzazione.

Chiavi e webhook

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. Ogni meccanismo si basa su una chiave. Per impostazione predefinita, viene usata la chiave di funzione denominata "default". Per usare una chiave diversa, configurare il provider di webhook per inviare il nome della chiave con la richiesta in uno dei modi seguenti:

  • Stringa di query: il provider passa il nome della chiave nel parametro della stringa di query clientid, ad esempio https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?clientid=<KEY_NAME>.
  • Intestazione della richiesta: il provider passa il nome della chiave nell'intestazione x-functions-clientid.

Tipi di contenuto

Il passaggio di dati binari e di moduli a una funzione non C# richiede l'uso dell'intestazione del tipo di contenuto appropriata. I tipi di contenuto supportati includono octet-stream per i dati binari e i tipi multipart.

Problemi noti

Nelle funzioni non C# le richieste inviate con il tipo di image/jpeg contenuto generano un string valore passato alla funzione. In questi casi, è possibile convertire manualmente il string valore in una matrice di byte per accedere ai dati binari non elaborati.

Limiti

La lunghezza della richiesta HTTP è limitata a 100 MB (104.857.600 byte) e la lunghezza dell'URL è limitata a 4 KB (4096 byte). Questi limiti vengono specificati dall'elemento httpRuntime del file web.config del runtime.

Se una funzione che usa il trigger HTTP non viene completata entro 230 secondi, Azure Load Balancer raggiungerà il timeout e restituirà un errore HTTP 502. La funzione rimarrà in esecuzione, ma non riuscirà a restituire una risposta HTTP. Per le funzioni con esecuzione prolungata, è consigliabile seguire modelli asincroni e restituire una posizione in cui è possibile effettuare il ping dello stato della richiesta. Per informazioni su quanto tempo può durare l'esecuzione di una funzione, vedere Scalabilità e hosting - Piano a consumo.

Passaggi successivi