HTTP-Trigger in Azure Functions

Mit dem HTTP-Trigger können Sie eine Funktion mit einer HTTP-Anforderung aufrufen. Sie können einen HTTP-Trigger zum Erstellen von serverlosen APIs und zum Antworten auf Webhooks verwenden.

Der Standardrückgabewert für eine HTTP-ausgelöste Funktion ist:

  • HTTP 204 No Content bei leerem Hauptteil in Functions 2.x und höher
  • HTTP 200 OK bei leerem Hauptteil in Functions 1.x

Um die HTTP-Antwort zu ändern, konfigurieren Sie eine Ausgabebindung.

Weitere Informationen zu HTTP-Bindungen finden Sie in der Übersicht und Referenz für die Ausgabebindung.

Tipp

Wenn Sie die HTTP- oder WebHook-Bindungen verwenden möchten, vermeiden Sie die Portauslastung, die durch nicht ordnungsgemäße Instanziierung von HttpClient verursacht werden kann. Weitere Informationen finden Sie unter How to manage connections in Azure Functions (Verwalten von Verbindungen in Azure Functions).

Beispiel

Das folgende Beispiel zeigt eine C#-Funktion, die in der Abfragezeichenfolge oder im Text der HTTP-Anforderung nach einem name-Parameter sucht. Beachten Sie, dass der Rückgabewert für die Ausgabebindung verwendet wird, jedoch kein Attribut vom Rückgabewert erforderlich ist.

[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");
}

Attribute und Anmerkungen

In C#-Klassenbibliotheken und Java ist das HttpTrigger-Attribut verfügbar, um die Funktion zu konfigurieren.

Sie können die Autorisierungsebene und die zulässigen HTTP-Methoden in Attributkonstruktorparametern, den Webhooktyp und eine Routenvorlage festlegen. Weitere Informationen zu diesen Einstellungen finden Sie unter Konfiguration.

In diesem Beispiel wird veranschaulicht, wie das HttpTrigger-Attribut verwendet wird.

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

Ein vollständiges Beispiel finden Sie unter Triggerbeispiel.

Konfiguration

Die folgende Tabelle gibt Aufschluss über die Bindungskonfigurationseigenschaften, die Sie in der Datei function.json und im Attribut HttpTrigger festlegen:

Eigenschaft von „function.json“ Attributeigenschaft BESCHREIBUNG
type Erforderlich – muss auf httpTrigger festgelegt sein.
direction Erforderlich – muss auf in festgelegt sein.
name Erforderlich – der Variablenname, der im Funktionscode für die Anforderung oder den Anforderungstext verwendet wird.
authLevel AuthLevel Bestimmt, welche Schlüssel (sofern erforderlich) in der Anforderung vorhanden sein müssen, um die Funktion aufzurufen. Bei den Autorisierungsebenen kann es sich um einen der folgenden Werte handeln:
  • anonymous: Es ist kein API-Schlüssel erforderlich.
  • function: Es ist ein funktionsspezifischer API-Schlüssel erforderlich. Dies ist der Standardwert, wenn kein anderer Wert angegeben wird.
  • admin: Der Hauptschlüssel ist erforderlich.
Weitere Informationen finden Sie im Abschnitt zu Autorisierungsschlüsseln.
methods Methoden Ein Array der HTTP-Methoden, auf die diese Funktion antwortet. Wird dieses Array nicht angegeben, antwortet die Funktion auf alle HTTP-Methoden. Siehe Anpassen des HTTP-Endpunkts.
route Route Definiert die Routenvorlage, mit der gesteuert wird, auf welche Anforderungs-URLs die Funktion antwortet. Wenn kein anderer Wert angegeben wird, lautet der Standardwert <functionname>. Weitere Informationen finden Sie unter Anpassen des HTTP-Endpunkts.
webHookType WebHookType Nur für die Laufzeit der Version 1.x unterstützt.

Konfiguriert den HTTP-Trigger so, dass er als Webhookempfänger für den angegebenen Anbieter fungiert. Legen Sie die methods Eigenschaft nicht fest, wenn Sie diese Eigenschaft festlegen. Der Webhooktyp kann folgende Werte annehmen:
  • genericJson: Ein allgemeiner Webhookendpunkt ohne Logik für einen bestimmten Anbieter. Diese Einstellung beschränkt Anforderungen auf solche, die HTTP POST verwenden und den Inhaltstyp application/json aufweisen.
  • github: Die Funktion antwortet auf GitHub-Webhooks. Verwenden Sie die authLevel-Eigenschaft nicht mit GitHub-Webhooks. Weitere Informationen finden Sie im Abschnitt zu GitHub-Webhooks weiter unten in diesem Artikel.
  • slack: Die Funktion antwortet auf Slack-Webhooks. Verwenden Sie die authLevel-Eigenschaft nicht mit Slack-Webhooks. Weitere Informationen finden Sie im Abschnitt zu Slack-Webhooks weiter unten in diesem Artikel.

Nutzlast

Der Triggereingabetyp wird entweder als HttpRequest oder als benutzerdefinierter Typ deklariert. Wenn Sie HttpRequest auswählen, erhalten Sie Vollzugriff auf das Anforderungsobjekt. Bei einem benutzerdefinierten Typ versucht die Laufzeit, den JSON-Anforderungstext zu analysieren, um die Objekteigenschaften festzulegen.

Anpassen des HTTP-Endpunkts

Wenn Sie eine Funktion für einen HTTP-Trigger erstellen, ist die Funktion mit einer Route der folgenden Form erreichbar:

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

Sie können diese Route mit der optionalen route-Eigenschaft in der Eingabebindung des HTTP-Triggers anpassen. In diesem Beispiel wird mit der Datei function.json eine route-Eigenschaft für einen HTTP-Trigger definiert:

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

Mit dieser Konfiguration ist die Funktion jetzt über die folgende Route erreichbar, anstatt über die ursprüngliche Route.

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

Diese Konfiguration gestattet dem Funktionscode, zwei Parameter in der Adresse unterstützen: category und id. Weitere Informationen dazu, wie Routenparameter in einer URL mit einem Token versehen werden, finden Sie unter Routing in ASP.NET Core.

Sie können für Ihre Parameter eine beliebige Web-API-Routeneinschränkung verwenden. Im folgenden C#-Funktionscode werden beide Parameter verwendet.

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

Standardmäßig verfügen alle Funktionsrouten über das Präfix api. Sie können das Präfix auch mit der extensions.http.routePrefix-Eigenschaft in der Datei host.json anpassen oder entfernen. Im folgenden Beispiel wird das Routenpräfix api entfernt, indem in der Datei host.json eine leere Zeichenfolge als Präfix verwendet wird.

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

Verwenden von Routenparametern

Routenparameter, die das Muster route einer Funktion definiert haben, sind für jede Bindung verfügbar. Wenn Sie beispielsweise eine Route als "route": "products/{id}" definiert haben, kann eine Tabellenspeicherbindung den Wert des Parameters {id} in der Bindungskonfiguration verwenden.

Die folgende Konfiguration zeigt, wie der Parameter {id} an das rowKey-Element der Bindung übergeben wird:

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

Wenn Sie Routenparameter verwenden, wird automatisch eine invoke_URL_template für Ihre Funktion erstellt. Die Clients können die URL-Vorlage verwenden, um zu wissen, welche Parameter sie beim Aufrufen Ihrer Funktion an die URL übergeben müssen. Navigieren Sie im Azure-Portal zu einer der durch HTTP ausgelösten Funktionen, und wählen Sie Funktions-URL abrufen aus.

Sie können programmgesteuert auf die invoke_URL_template zugreifen, indem Sie die Azure Resource Manager-APIs Funktionen auflisten oder Funktionen abrufen verwenden.

Arbeiten mit Clientidentitäten

Wenn Ihre Funktions-App App Service-Authentifizierung/-Autorisierung verwendet, können Sie Informationen über authentifizierte Clients aus Ihrem Code anzeigen. Diese Informationen sind als von der Plattform eingefügter Anforderungsheader verfügbar.

Sie können diese Informationen auch aus Datenbindungen auslesen. Diese Funktion ist nur für die Functions-Runtime 2.x und höher verfügbar. Sie ist derzeit auch nur für .NET-Sprachen verfügbar.

Informationen zu authentifizierten Clients sind als ClaimsPrincipal verfügbar. „ClaimsPrincipal“ ist als Teil des Anforderungskontextes verfügbar, wie im folgenden Beispiel gezeigt:

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

Alternativ kann „ClaimsPrincipal“ einfach als zusätzlicher Parameter in die Funktionssignatur aufgenommen werden:

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

Funktionszugriffsschlüssel

Mit Functions können Sie Schlüssel verwenden, wodurch der Zugriff auf Ihre HTTP-Funktionsendpunkte während der Entwicklung erschwert wird. Sofern die HTTP-Zugriffsebene für eine über HTTP ausgelöste Funktion nicht auf anonymous festgelegt ist, müssen Anforderungen einen API-Zugriffsschlüssel in der Anforderung enthalten.

Schlüssel bieten zwar einen Standardsicherheitsmechanismus, für den Schutz eines HTTP-Endpunkts in der Produktion sollten jedoch gegebenenfalls zusätzliche Optionen in Erwägung gezogen werden. So ist es beispielsweise in der Regel nicht empfehlenswert, den gemeinsamen geheimen Schlüssel in öffentlichen Apps zu verteilen. Wenn Ihre Funktion über einen öffentlichen Client aufgerufen wird, empfiehlt es sich gegebenenfalls, einen anderen Sicherheitsmechanismus zu implementieren. Weitere Informationen hierzu finden Sie unter Schützen eines HTTP-Endpunkts in einer Produktionsumgebung.

Wenn Sie Ihre Funktionsschlüsselwerte erneuern, müssen die aktualisierten Schlüsselwerte manuell an alle Clients verteilt werden, von denen Ihre Funktion aufgerufen wird.

Autorisierungsbereiche (Funktionsebene)

Es gibt zwei Zugriffsbereiche für Schlüssel auf Funktionsebene:

  • Funktion: Diese Schlüssel gelten nur für die Funktionen, für die sie definiert sind. Bei Verwendung als API-Schlüssel ermöglichen diese nur Zugriff auf diese spezielle Funktion.

  • Host: Schlüssel mit einem Hostbereich können für den Zugriff auf alle Funktionen in der Funktions-App verwendet werden. Bei Verwendung als API-Schlüssel ermöglichen diese Zugriff auf jede Funktion in der Funktionen-App.

Jeder Schlüssel ist zu Referenzzwecken benannt. Auf Funktions- und Hostebene gibt es einen Standardschlüssel (mit dem Namen „default“). Funktionsschlüssel haben Vorrang vor Hostschlüsseln. Wenn zwei Schlüssel mit dem gleichen Namen definiert wurden, wird immer der Funktionsschlüssel verwendet.

Hauptschlüssel (Administratorebene)

Jede Funktions-App verfügt außerdem über einen Hostschlüssel auf Administratorebene mit dem Namen _master. Zusätzlich zur Bereitstellung des Zugriffs auf Hostebene auf alle Funktionen in der App bietet der Hauptschlüssel auch administrativen Zugriff auf die Laufzeit-REST-APIs. Dieser Schlüssel kann nicht widerrufen werden. Wenn Sie die Zugriffsebene admin festlegen, muss für Anforderungen der Hauptschlüssel verwendet werden. Alle anderen Schlüssel führen zu einem Zugriffsfehler.

Achtung

Aufgrund der erhöhten Berechtigungen, die der Hauptschlüssel in Ihrer Funktions-App gewährt, sollten Sie diesen Schlüssel nicht für Dritte freigeben oder in nativen Clientanwendungen verteilen. Gehen Sie umsichtig vor, wenn Sie die Zugriffsebene „Administrator“ auswählen.

Abrufen von Schlüsseln

Schlüssel werden als Teil Ihrer Funktionen-App in Azure gespeichert und sind im Ruhezustand verschlüsselt. Um vorhandene Schlüssel anzuzeigen, neue Schlüssel zu erstellen oder Schlüsseln neue Werte zuzuweisen, navigieren Sie im Azure-Portal zu einer Ihrer über HTTP ausgelösten Funktionen, und wählen Sie Funktionsschlüssel aus.

Sie können auch Hostschlüssel verwalten. Navigieren Sie im Azure-Portal zur Funktions-App, und wählen Sie App-Schlüssel aus.

Sie können Funktions- und Hostschlüssel programmgesteuert über die Azure Resource Manager-APIs abrufen. Es gibt APIs zum Auflisten von Funktionsschlüsseln und zum Auflisten von Hostschlüsseln. Wenn Sie Bereitstellungsslots verwenden, nutzen Sie entsprechend die APIs zum Auflisten von Funktionsschlüsseln für Slots bzw. zum Auflisten von Hostschlüsseln für Slots.

Sie können mit den APIs Funktionsgeheimnis erstellen oder aktualisieren, Funktionsgeheimnis für Slots erstellen oder aktualisieren, Hostgeheimnis erstellen oder aktualisieren und Hostgeheimnis für Slots erstellen oder aktualisieren auch programmgesteuert neue Funktions- und Hostschlüssel erstellen.

Löschen können Sie Funktions- und Hostschlüssel programmgesteuert über die APIs Funktionsgeheimnis löschen, Funktionsgeheimnis für Slots löschen, Hostgeheimnis löschen und Hostgeheimnis für Slots löschen.

Sie können auch die Legacy-APIs für die Schlüsselverwaltung verwenden, um Funktionsschlüssel abzurufen. Es wird jedoch empfohlen, die Azure Resource Manager-APIs zu verwenden.

Autorisierung per API-Schlüssel

Für die meisten HTTP-Triggervorlagen muss in der Anforderung ein API-Schlüssel vorhanden sein. Ihre HTTP-Anforderung sieht daher normalerweise wie folgende URL aus:

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

Der Schlüssel kann in einer Abfragezeichenfolgenvariablen namens code (wie oben zu sehen) enthalten sein. Er kann auch in einem x-functions-key-HTTP-Header enthalten sein. Der Wert des Schlüssels kann ein beliebiger für die Funktion definierter Funktionsschlüssel oder ein beliebiger Hostschlüssel sein.

Sie können anonyme Anforderungen zulassen, die keine Schlüssel erfordern. Sie können auch anfordern, dass der Hauptschlüssel verwendet wird. Zum Ändern der Standardautorisierungsstufe verwenden Sie die authLevel-Eigenschaft in der Bindungs-JSON. Weitere Informationen finden Sie unter Trigger: Konfiguration.

Hinweis

Beim lokalen Ausführen von Funktionen ist die Autorisierung unabhängig von der festgelegten Autorisierungsebene deaktiviert. Die authLevel-Einstellung in Ihrem Trigger wird nach der Veröffentlichung in Azure angewendet. Schlüssel sind auch bei lokaler Ausführung in einem Container weiterhin erforderlich.

Schützen eines HTTP-Endpunkts in einer Produktionsumgebung

Wenn Sie Ihre Funktionsendpunkte in einer Produktionsumgebung umfassend schützen möchten, sollten Sie eine der folgenden Sicherheitsoptionen auf Funktions-App-Ebene implementieren. Wenn Sie eine dieser Sicherheitsmethoden auf Funktions-App-Ebene verwenden, sollten Sie die Autorisierungsebene der über HTTP ausgelösten Funktion auf anonymous festlegen.

Aktivieren der App Service-Authentifizierung/-Autorisierung

Die App Service-Plattform ermöglicht die Verwendung von Azure Active Directory (AAD) sowie von verschiedenen anderen Identitätsanbietern zum Authentifizieren von Clients. Sie können diese Strategie zum Implementieren von benutzerdefinierten Autorisierungsregeln für Ihre Funktionen sowie Benutzerinformationen aus Ihrem Funktionscode verwenden. Weitere Informationen finden Sie unter Authentifizierung und Autorisierung in Azure App Service und Arbeiten mit Clientidentitäten.

Verwenden von Azure API Management (APIM) zum Authentifizieren von Anforderungen

APIM stellt verschiedene API-Sicherheitsoptionen für eingehende Anforderungen bereit. Weitere Informationen hierzu finden Sie unter API Management-Authentifizierungsrichtlinien. Wenn APIM vorhanden ist, können Sie Ihre Funktions-App so konfigurieren, dass Anforderungen nur von den IP-Adressen Ihrer APIM-Instanz angenommen werden. Weitere Informationen hierzu finden Sie unter Einschränkungen für IP-Adressen.

Isoliertes Bereitstellen Ihrer Funktions-App

Die Azure App Service-Umgebung (ASE) stellt eine spezielle Hostingumgebung bereit, in der Sie Ihre Funktionen ausführen können. Mit ASE können Sie ein Front-End-Gateway konfigurieren, das Sie zum Authentifizieren aller eingehenden Anforderungen verwenden können. Weitere Informationen hierzu finden Sie unter Konfigurieren einer Web Application Firewall (WAF) für eine App Service-Umgebung.

webhooks

Hinweis

Der Webhookmodus ist nur für die Version 1.x der Functions-Laufzeit verfügbar. Diese Änderung wurde vorgenommen, um die Leistung von HTTP-Triggern in Version 2.x und höheren Versionen zu verbessern.

In Version 1.x stellen Webhookvorlagen zusätzliche Überprüfungsoptionen für Webhooknutzlasten bereit. In Version 2.x und höheren Versionen kann der HTTP-Basistrigger weiterhin verwendet werden. Zudem wird er für Webhooks empfohlen.

GitHub-Webhooks

Erstellen Sie zum Antworten auf GitHub-Webhooks zuerst eine Funktion mit einem HTTP-Trigger, und legen Sie die webHookType-Eigenschaft auf github fest. Kopieren Sie dann die URL und den API-Schlüssel auf die Seite Webhook hinzufügen Ihres GitHub-Repositorys.

Screenshot: Hinzufügen eines Webhooks für Ihre Funktion

Slack-Webhooks

Der Slack-Webhook lässt Sie das Token nicht angeben, sondern generiert es für Sie. Daher müssen Sie einen funktionsspezifischen Schlüssel mit dem Token aus Slack konfigurieren. Weitere Informationen finden Sie unter Autorisierungsschlüssel.

Webhooks und Schlüssel

Die Webhookautorisierung wird von der Empfangskomponente für Webhooks verarbeitet, die zum HTTP-Trigger gehört. Der Mechanismus variiert je nach Webhooktyp. Für jeden Mechanismus wird ein Schlüssel benötigt. Standardmäßig wird der Funktionsschlüssel namens „default“ verwendet. Um einen anderen Schlüssel zu verwenden, konfigurieren Sie den Webhookanbieter, sodass der Schlüsselname auf eine der folgenden Arten mit der Anforderung gesendet wird:

  • Abfragezeichenfolge: Der Anbieter übergibt den Schlüsselnamen im clientid-Abfragezeichenfolgenparameter, z. B. https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?clientid=<KEY_NAME>.
  • Anforderungsheader: Der Anbieter übergibt den Schlüsselnamen im x-functions-clientid-Header.

Inhaltstypen

Bei der Übergabe von Binär- und Formulardaten an eine C#-fremde Funktion muss der passende Content-Type-Header verwendet werden. Zu den unterstützten Inhaltstypen zählt octet-stream für Binärdaten und mehrteilige Typen.

Bekannte Probleme

In C#-fremden Funktionen wird bei Anforderungen, die mit dem Inhaltstyp image/jpeg gesendet werden, ein Wert vom Typ string an die Funktion übergeben. In einem solchen Fall können Sie den Wert vom Typ string manuell in ein Bytearray konvertieren, um auf die unformatierten Binärdaten zuzugreifen.

Einschränkungen

Die Länge der HTTP-Anforderung ist auf 100 MB (104.857.600 Bytes) und die URL-Länge auf 4 KB (4.096 Bytes) beschränkt. Diese Grenzwerte werden durch das httpRuntime-Element der Datei Web.config der Runtime angegeben.

Wenn eine Funktion, die den HTTP-Trigger verwendet, nicht innerhalb von etwa 230 Sekunden abgeschlossen ist, tritt bei Azure Load Balancer ein Timeout auf, und es wird ein HTTP 502-Fehler zurückgegeben. Die Funktion wird weiterhin ausgeführt, kann aber keine HTTP-Antwort zurückgeben. Bei Funktionen mit langer Ausführungsdauer empfiehlt es sich, asynchrone Muster zu befolgen und einen Speicherort zurückzugeben, von dem aus Sie den Status der Anforderung pingen können. Informationen dazu, wie lang eine Funktion ausgeführt werden kann, finden Sie unter Skalierung und Hosting – Verbrauchsplan.

Nächste Schritte