Azure Functions HTTP-utlösare

Med HTTP-utlösaren kan du anropa en funktion med en HTTP-begäran. Du kan använda en HTTP-utlösare för att skapa serverlösa API:er och svara på webhooks.

Standardreturvärdet för en HTTP-utlöst funktion är:

  • HTTP 204 No Content med en tom brödtext i Functions 2.x och senare
  • HTTP 200 OK med en tom brödtext i Functions 1.x

Om du vill ändra HTTP-svaret konfigurerar du en utdatabindning.

Mer information om HTTP-bindningar finns i översikten och utdatabindningsreferensen.

Tips

Om du planerar att använda HTTP-eller webhook-bindningarna bör du planera för att undvika att port överbelastningen kan orsakas av felaktig instansiering av HttpClient . Mer information finns i hantera anslutningar i Azure Functions.

Exempel

I följande exempel visas en C#-funktion som söker efter en name parameter antingen i frågesträngen eller brödtexten i HTTP-begäran. Observera att returvärdet används för utdatabindningen, men ett returvärdesattribut krävs inte.

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

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

Attribut och anteckningar

I C#-klassbibliotek och Java HttpTrigger är attributet tillgängligt för att konfigurera funktionen.

Du kan ange auktoriseringsnivå och tillåtna HTTP-metoder i attributkonstruktorparametrar, webhooktyp och en vägmall. Mer information om de här inställningarna finns i konfiguration.

Det här exemplet visar hur du använder attributet HttpTrigger.

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

Ett fullständigt exempel finns i utlösarexempel.

Konfiguration

I följande tabell beskrivs de bindningskonfigurationsegenskaper som du anger ifunction.jspå filen och HttpTrigger attributet .

function.jspå egenskapen Attributegenskap Description
Typ saknas Obligatoriskt – måste anges till httpTrigger .
riktning saknas Obligatoriskt – måste anges till in .
Namn saknas Obligatoriskt – variabelnamnet som används i funktionskoden för begäran eller begärandetexten.
authLevel AuthLevel Avgör vilka nycklar, om några, som måste finnas i begäran för att anropa funktionen. Auktoriseringsnivån kan vara något av följande värden:
  • anonymous—Ingen API-nyckel krävs.
  • function—En funktionsspecifik API-nyckel krävs. Det här är standardvärdet om inget anges.
  • admin—Huvudnyckeln krävs.
Mer information finns i avsnittet om auktoriseringsnycklar.
Metoder Metoder En matris med HTTP-metoderna som funktionen svarar på. Om inget anges svarar funktionen på alla HTTP-metoder. Se anpassa HTTP-slutpunkten.
route Rutt Definierar vägmallen och styr vilka begärande-URL:er som din funktion svarar på. Standardvärdet om inget anges är <functionname> . Mer information finns i anpassa HTTP-slutpunkten.
webHookType WebHookType Stöds endast för version 1.x-körningen.

Konfigurerar HTTP-utlösaren så att den fungerar som en webhook-mottagare för den angivna providern. Ange inte egenskapen om methods du anger den här egenskapen. Webhook-typen kan vara något av följande värden:
  • genericJson—En generell webhook-slutpunkt utan logik för en specifik provider. Den här inställningen begränsar begäranden till endast de som använder HTTP POST och application/json med innehållstyp.
  • github—Funktionen svarar på GitHub webhooks. Använd inte egenskapen authLevel med GitHub webhooks. Mer information finns i avsnittet GitHub webhooks senare i den här artikeln.
  • slack—Funktionen svarar på Slack-webhooks. Använd inte egenskapen authLevel med Slack-webhooks. Mer information finns i avsnittet om Slack-webhooks senare i den här artikeln.

Nyttolast

Utlösarindatatypen deklareras som HttpRequest antingen eller en anpassad typ. Om du väljer HttpRequest får du fullständig åtkomst till begärandeobjektet. För en anpassad typ försöker körningen parsa JSON-begärandetexten för att ange objektegenskaperna.

Anpassa HTTP-slutpunkten

Som standard när du skapar en funktion för en HTTP-utlösare är funktionen adresserbar med en väg i formuläret:

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

Du kan anpassa den här vägen med hjälp av den route valfria egenskapen för HTTP-utlösarens indatabindning. Till exempel definierar följandefunction.js på filen en egenskap för route en HTTP-utlösare:

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

Med den här konfigurationen är funktionen nu adresserbar med följande väg i stället för den ursprungliga vägen.

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

Med den här konfigurationen kan funktionskoden stödja två parametrar i adressen, kategorin och ID:t. Mer information om hur vägparametrar tokeniseras i en URL finns i Routning i ASP.NET Core.

Du kan använda en begränsning för web-API-väg med dina parametrar. Följande C#-funktionskod använder båda parametrarna.

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

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

Som standard föregås alla funktionsvägar av api:et. Du kan också anpassa eller ta bort prefixet med extensions.http.routePrefix hjälp av egenskapen ihost.js filen. I följande exempel tas API-vägprefixet bort med hjälp av en tom sträng för prefixet ihost.js filen.

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

Använda vägparametrar

Vägparametrar som definierade en funktions mönster route är tillgängliga för varje bindning. Om du till exempel har en väg definierad som kan en tabellagringsbindning använda värdet för "route": "products/{id}" {id} parametern i bindningskonfigurationen.

Följande konfiguration visar hur {id} parametern skickas till bindningens rowKey .

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

När du använder vägparametrar skapas invoke_URL_template en automatiskt för din funktion. Klienterna kan använda URL-mallen för att förstå de parametrar som de behöver skicka in URL:en när de anropar funktionen med hjälp av dess URL. Gå till någon av dina HTTP-utlösta funktioner i Azure Portal välj Hämta funktions-URL.

Du kan komma åt programmatiskt invoke_URL_template med hjälp av Azure Resource Manager-API:er för List Functions eller Get Function.

Arbeta med klientidentiteter

Om funktionsappen använder App Service autentisering/auktoriseringkan du visa information om autentiserade klienter från din kod. Den här informationen är tillgänglig som begärandehuvuden som matas in av plattformen.

Du kan också läsa den här informationen från bindningsdata. Den här funktionen är endast tillgänglig för Functions-körningen i 2.x och senare. Den är för närvarande endast tillgänglig för .NET-språk.

Information om autentiserade klienter är tillgänglig som en ClaimsPrincipal. ClaimsPrincipal är tillgängligt som en del av begärandekontexten enligt följande exempel:

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

Alternativt kan ClaimsPrincipal bara inkluderas som en ytterligare parameter i funktionssignaturen:

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

Funktionsåtkomstnycklar

Med funktioner kan du använda nycklar för att göra det svårare att komma åt HTTP-funktionerna under utvecklingen. Om inte HTTP-filnivån på en HTTP-utlöst funktion har angetts till anonymous måste begär Anden innehålla en API-åtkomst nyckel i begäran.

Även om nycklar ger en standardmekanism för säkerhetsmekanism, kanske du vill överväga ytterligare alternativ för att skydda en HTTP-slutpunkt i produktionen. Det är till exempel vanligt vis inte en bra idé att distribuera delad hemlighet i offentliga appar. Om din funktion anropas från en offentlig klient kanske du vill överväga att implementera en annan säkerhetsmekanism. Mer information finns i skydda en HTTP-slutpunkt i produktion.

När du förnyar funktions nyckel värden måste du manuellt distribuera de uppdaterade nyckelvärdena till alla klienter som anropar din funktion.

Authorization-omfattningar (funktions nivå)

Det finns två åtkomstscope för nycklar på funktions nivå:

  • Funktion: dessa nycklar gäller endast för de funktioner som de är definierade under. När den används som en API-nyckel tillåter dessa endast åtkomst till den funktionen.

  • Värd: nycklar med ett värd omfång kan användas för att få åtkomst till alla funktioner i Function-appen. När den används som en API-nyckel tillåter dessa åtkomst till alla funktioner i Function-appen.

Varje nyckel namnges som referens och det finns en standard nyckel (med namnet "standard") på funktion-och värdnivå. Funktions tangenter prioriteras framför värd nycklar. När två nycklar definieras med samma namn används alltid funktions nyckeln.

Huvud nyckel (admin-nivå)

Varje Function-app har också en värd nyckel på administratörs nivå med namnet _master . Förutom att tillhandahålla åtkomst på värdnivå till alla funktioner i appen, ger huvud nyckeln även administrativ åtkomst till REST-API: erna för körning. Den här nyckeln kan inte återkallas. När du anger en åtkomst nivå för admin måste begär Anden använda huvud nyckeln. eventuella andra nycklar leder till att åtkomsten Miss lyckas.

Varning

På grund av de utökade behörigheterna i din Function-app som beviljats av huvud nyckeln bör du inte dela den här nyckeln med tredje part eller distribuera den i interna klient program. Använd försiktighet när du väljer administratörs åtkomst nivå.

Hämta nycklar

Nycklar lagras som en del av din funktionsapp i Azure och krypteras i vila. Om du vill visa dina nycklar, skapa nya eller återställa nycklar till nya värden navigerar du till någon av dina HTTP-utlösta funktioner i Azure Portal och väljer Funktionsnycklar.

Du kan också hantera värdnycklar. Gå till funktionsappen i Azure Portal och välj Appnycklar.

Du kan hämta funktions- och värdnycklar programmatiskt med hjälp av Azure Resource Manager-API:er. Det finns API:er för att visa en lista över funktionsnycklar och lista värdnycklar, och när du använder distributionsfack är motsvarande API:er List Function Keys Slot (Lista över funktionsnycklar) och List Host Keys Slot (Lista värdnycklar).

Du kan också skapa nya funktions- och värdnycklar programmatiskt med hjälp av skapa eller uppdatera funktionshemlighet, skapa eller uppdatera funktionshemlighetsplats, skapa eller uppdatera värdhemlighet och skapa eller uppdatera värdhemlighetsplats-API:er.

Funktions- och värdnycklar kan tas bort programmatiskt med hjälp av API:erna Tabort funktionshemlighet, Ta bort funktionshemlighet, Ta bort värdhemlighet och Ta bort värdhemlighetsplats.

Du kan också använda de äldre API:erna förnyckelhantering för att hämta funktionsnycklar, men Azure Resource Manager-API:er rekommenderas i stället.

Auktorisering av API-nyckel

De flesta HTTP-utlösarmallar kräver en API-nyckel i begäran. Http-begäran ser därför normalt ut som följande URL:

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

Nyckeln kan inkluderas i en frågesträngsvariabel med code namnet , som ovan. Det kan också inkluderas i ett x-functions-key HTTP-huvud. Värdet för nyckeln kan vara valfri funktionsnyckel som definierats för funktionen eller valfri värdnyckel.

Du kan tillåta anonyma begäranden som inte kräver nycklar. Du kan också kräva att huvudnyckeln används. Du ändrar standardauktoriseringsnivån med hjälp av authLevel egenskapen i bindnings-JSON. Mer information finns i Utlösare – konfiguration.

Anteckning

När du kör funktioner lokalt inaktiveras auktorisering oavsett den angivna inställningen för auktoriseringsnivå. När du har publicerat till Azure authLevel tillämpas inställningen i utlösaren. Nycklar krävs fortfarande när du kör lokalt i en container.

Skydda en HTTP-slutpunkt i produktion

För att helt skydda dina funktionsslutpunkter i produktion bör du överväga att implementera något av följande säkerhetsalternativ på funktionsappnivå. När du använder någon av dessa säkerhetsmetoder på funktionsappnivå bör du ange den HTTP-utlösta funktionauktoriseringsnivån till anonymous .

Aktivera App Service autentisering/auktorisering

App Services plattformen gör att du kan använda Azure Active Directory (AAD) och flera identitets leverantörer från tredje part för att autentisera klienter. Du kan använda den här strategin för att implementera anpassade auktoriseringsregler för dina funktioner och du kan arbeta med användar information från funktions koden. Mer information finns i autentisering och auktorisering i Azure App Service och arbeta med klient identiteter.

Använda Azure API Management (APIM) för att autentisera begär Anden

APIM tillhandahåller flera olika API-säkerhetsalternativ för inkommande begär Anden. Läs mer i API Management autentiseringsprinciper. Med APIM på plats kan du konfigurera Function-appen så att den endast accepterar begär Anden från IP-adressen för din APIM-instans. Mer information finns i begränsningar för IP-adresser.

Distribuera funktionsappen isolerat

Azure App Service Environment (ASE) tillhandahåller en dedikerad värd miljö där funktionerna ska köras. Med ASE kan du konfigurera en enda klient dels-gateway som du kan använda för att autentisera alla inkommande begär Anden. Mer information finns i Konfigurera en brand vägg för webbaserade program (WAF) för App Service-miljön.

Webhooks

Anteckning

Webhook-läget är endast tillgängligt för version 1.x av Functions-körningen. Den här ändringen har gjorts för att förbättra prestanda för HTTP-utlösare i version 2.x och senare.

I version 1.x tillhandahåller webhook-mallar ytterligare validering för webhook-nyttolaster. I version 2.x och senare fungerar fortfarande den grundläggande HTTP-utlösaren och är den rekommenderade metoden för webhooks.

GitHub webhooks

För att svara GitHub webhooks skapar du först funktionen med en HTTP-utlösare och anger egenskapen webHookType till github . Kopiera sedan dess URL och API-nyckel till sidan Lägg till webhook för din GitHub lagringsplats.

Skärmbild som visar hur du lägger till en webhook för din funktion.

Slack-webhooks

Slack-webhooken genererar en token åt dig i stället för att låta dig ange den, så du måste konfigurera en funktionsspecifik nyckel med token från Slack. Se Auktoriseringsnycklar.

Webhooks och nycklar

Webhook-auktorisering hanteras av webhook-mottagarkomponenten, en del av HTTP-utlösaren, och mekanismen varierar beroende på webhook-typen. Varje mekanism förlitar sig på en nyckel. Som standard används funktionsnyckeln med namnet "default". Om du vill använda en annan nyckel konfigurerar du webhook-providern för att skicka nyckelnamnet med begäran på något av följande sätt:

  • Frågesträng: Providern skickar nyckelnamnet i clientid frågesträngparametern, till exempel https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?clientid=<KEY_NAME> .
  • Begärandehuvud: Providern skickar nyckelnamnet i x-functions-clientid rubriken.

Innehållstyper

För att skicka binära data och formulärdata till en icke-C#-funktion måste du använda lämpligt innehållstypshuvud. Innehållstyper som stöds octet-stream är för binära data och flerpartstyper.

Kända problem

I icke-C#-funktioner resulterar begäranden som skickas med image/jpeg innehållstypen i ett string värde som skickas till funktionen. I sådana fall kan du manuellt konvertera värdet till en string bytematris för att få åtkomst till binära rådata.

Gränser

HTTP-begärans längd är begränsad till 100 MB (104 857 600 byte) och URL-längden är begränsad till 4 kB (4 096 byte). Dessa gränser anges av httpRuntime -elementet i körningsfilens Web.config.

Om en funktion som använder HTTP-utlösaren inte slutförs inom 230 sekunder Azure Load Balancer time out och returnerar ett HTTP 502-fel. Funktionen fortsätter att köras men kan inte returnera ett HTTP-svar. För långvariga funktioner rekommenderar vi att du följer asynkrona mönster och returnerar en plats där du kan pinga status för begäran. Information om hur länge en funktion kan köras finns i Skala och värdskap – Förbrukningsplan.

Nästa steg