Wyzwalacz HTTP usługi Azure Functions

Wyzwalacz HTTP umożliwia wywołanie funkcji z żądaniem HTTP. Wyzwalacz HTTP umożliwia tworzenie bezserwerowych interfejsów API i reagowanie na elementy webhook.

Domyślna wartość zwracana dla funkcji wyzwalanej przez protokół HTTP to:

  • HTTP 204 No Content z pustą treścią w usłudze Functions w wersji 2.x lub nowszej
  • HTTP 200 OK z pustą treścią w usłudze Functions 1.x

Aby zmodyfikować odpowiedź HTTP, skonfiguruj powiązanie wyjściowe.

Aby uzyskać więcej informacji na temat powiązań HTTP, zobacz omówienie i odwołanie do powiązania wyjściowego.

Napiwek

Jeśli planujesz używać powiązań HTTP lub WebHook, zaplanuj uniknięcie wyczerpania portów HttpClient, które mogą być spowodowane przez niewłaściwe utworzenie wystąpienia elementu . Aby uzyskać więcej informacji, zobacz Jak zarządzać połączeniami w usłudze Azure Functions.

Ważne

W tym artykule są używane karty do obsługi wielu wersji modelu programowania Node.js. Model w wersji 4 jest ogólnie dostępny i ma bardziej elastyczne i intuicyjne środowisko dla deweloperów języka JavaScript i Języka TypeScript. Aby uzyskać więcej informacji na temat sposobu działania modelu w wersji 4, zapoznaj się z przewodnikiem dewelopera dotyczącym usługi Azure Functions Node.js. Aby dowiedzieć się więcej o różnicach między wersjami 3 i v4, zapoznaj się z przewodnikiem migracji.

Usługa Azure Functions obsługuje dwa modele programowania dla języka Python. Sposób definiowania powiązań zależy od wybranego modelu programowania.

Model programowania w języku Python w wersji 2 umożliwia definiowanie powiązań przy użyciu dekoratorów bezpośrednio w kodzie funkcji języka Python. Aby uzyskać więcej informacji, zobacz przewodnik dla deweloperów języka Python.

Ten artykuł obsługuje oba modele programowania.

Przykład

Funkcję języka C# można utworzyć przy użyciu jednego z następujących trybów języka C#:

  • Model izolowanego procesu roboczego: skompilowana funkcja języka C#, która jest uruchamiana w procesie roboczym izolowanym od środowiska uruchomieniowego. Proces izolowanego procesu roboczego jest wymagany do obsługi funkcji języka C# uruchomionych w wersjach LTS i innych niż LTS platformy .NET oraz programu .NET Framework. Rozszerzenia dla izolowanych funkcji procesu roboczego używają Microsoft.Azure.Functions.Worker.Extensions.* przestrzeni nazw.
  • Model przetwarzania: skompilowana funkcja języka C#, która działa w tym samym procesie co środowisko uruchomieniowe usługi Functions. W odmianie tego modelu funkcje można uruchamiać przy użyciu skryptów języka C#, które są obsługiwane głównie w przypadku edytowania portalu języka C#. Rozszerzenia dla funkcji przetwarzania używają Microsoft.Azure.WebJobs.Extensions.* przestrzeni nazw.

Kod w tym artykule jest domyślnie używany w języku .NET Core w wersji 2.x i nowszej. Aby uzyskać informacje na temat składni 1.x, zobacz szablony funkcji 1.x.

W poniższym przykładzie pokazano wyzwalacz HTTP, który zwraca odpowiedź "hello, world" jako IActionResult przy użyciu integracji ASP.NET Core w środowisku .NET Isolated:

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

W poniższym przykładzie pokazano wyzwalacz HTTP, który zwraca odpowiedź "hello world" jako obiekt 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;
}

Ta sekcja zawiera następujące przykłady:

W poniższych przykładach pokazano powiązanie wyzwalacza HTTP.

Odczyt parametru z ciągu zapytania

W tym przykładzie odczytuje parametr o nazwie id, z ciągu zapytania i używa go do skompilowania dokumentu JSON zwróconego do klienta z typem application/jsonzawartości .

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

Odczytywanie treści z żądania POST

Ten przykład odczytuje treść żądania POST jako Stringelement i używa go do skompilowania dokumentu JSON zwróconego do klienta z typem application/jsonzawartości .

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

Odczytywanie parametru z trasy

W tym przykładzie odczytuje obowiązkowy parametr o nazwie idi opcjonalny parametr name ze ścieżki trasy i używa ich do skompilowania dokumentu JSON zwróconego do klienta z typem application/jsonzawartości .

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

Odczytywanie treści POJO z żądania POST

Oto kod klasy ToDoItem , do których odwołuje się ten przykład:


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

W tym przykładzie odczytuje treść żądania POST. Treść żądania zostanie automatycznie zserializowany do obiektu i zostanie zwrócona do klienta z typem ToDoItemapplication/jsonzawartości . Parametr ToDoItem jest serializowany przez środowisko uruchomieniowe usługi Functions, ponieważ jest przypisany do body właściwości HttpMessageResponse.Builder klasy.

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

W poniższym przykładzie przedstawiono funkcję TypeScript wyzwalacza HTTP. Funkcja szuka parametru name w ciągu zapytania lub treści żądania 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,
});

W poniższym przykładzie przedstawiono funkcję JavaScript wyzwalacza HTTP. Funkcja szuka parametru name w ciągu zapytania lub treści żądania 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}!` };
    },
});

W poniższym przykładzie pokazano powiązanie wyzwalacza w pliku function.json i funkcji programu PowerShell. Funkcja szuka parametru name w ciągu zapytania lub treści żądania 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
})

W poniższym przykładzie przedstawiono powiązanie wyzwalacza i funkcję języka Python, która używa powiązania. Funkcja szuka parametru name w ciągu zapytania lub treści żądania HTTP. Przykład zależy od tego, czy używasz modelu programowania w wersji 1, czy w wersji 2 języka Python.

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
        )

Atrybuty

Biblioteki języka C# procesu roboczego zarówno w procesie przetwarzania procesów procesowych, jak i izolowanych, używają HttpTriggerAttribute elementu , aby zdefiniować powiązanie wyzwalacza. Zamiast tego skrypt języka C# używa pliku konfiguracji function.json zgodnie z opisem w przewodniku obsługi skryptów języka C#.

W aplikacjach HttpTriggerAttribute funkcji izolowanego procesu roboczego obsługiwane są następujące parametry:

Parametry opis
AuthLevel Określa, jakie klucze, jeśli istnieją, muszą być obecne w żądaniu, aby wywołać funkcję. Aby uzyskać obsługiwane wartości, zobacz Poziom autoryzacji.
Metody Tablica metod HTTP, na które odpowiada funkcja. Jeśli nie zostanie określony, funkcja odpowiada na wszystkie metody HTTP. Zobacz Dostosowywanie punktu końcowego HTTP.
Trasa Definiuje szablon trasy, kontrolując, na które adresy URL żądań odpowiada funkcja. Wartość domyślna, jeśli żadna z nich nie jest podana, to <functionname>. Aby uzyskać więcej informacji, zobacz dostosowywanie punktu końcowego HTTP.

Dekoratory

Dotyczy tylko modelu programowania w wersji 2 języka Python.

W przypadku funkcji języka Python w wersji 2 zdefiniowanych przy użyciu dekoratora następujące właściwości wyzwalacza są definiowane w dekoratorze route , który dodaje powiązanie HttpTrigger i HttpOutput:

Właściwości opis
route Trasa dla punktu końcowego HTTP. Jeśli parametr None (Brak), zostanie ustawiona na nazwę funkcji , jeśli jest obecna lub zdefiniowana przez użytkownika nazwa funkcji języka Python.
trigger_arg_name Nazwa argumentu httpRequest. Wartość domyślna to "req".
binding_arg_name Nazwa argumentu httpResponse. Wartość domyślna to "$return".
methods Krotka metod HTTP, na które odpowiada funkcja.
auth_level Określa, jakie klucze, jeśli istnieją, muszą być obecne w żądaniu, aby wywołać funkcję.

Aby zapoznać się z funkcjami języka Python zdefiniowanymi przy użyciu function.json, zobacz sekcję Konfiguracja .

Adnotacje

W bibliotece środowiska uruchomieniowego funkcji Języka Java użyj adnotacji HttpTrigger, która obsługuje następujące ustawienia:

Konfigurowanie

Dotyczy tylko modelu programowania języka Python w wersji 1.

W poniższej tabeli opisano właściwości, które można ustawić dla options obiektu przekazanego app.http() do metody .

Właściwości opis
authLevel Określa, jakie klucze, jeśli istnieją, muszą być obecne w żądaniu, aby wywołać funkcję. Aby uzyskać obsługiwane wartości, zobacz Poziom autoryzacji.
Metody Tablica metod HTTP, na które odpowiada funkcja. Jeśli nie zostanie określony, funkcja odpowiada na wszystkie metody HTTP. Zobacz Dostosowywanie punktu końcowego HTTP.
Trasy Definiuje szablon trasy, kontrolując, na które adresy URL żądań odpowiada funkcja. Wartość domyślna, jeśli żadna z nich nie jest podana, to <functionname>. Aby uzyskać więcej informacji, zobacz dostosowywanie punktu końcowego HTTP.

W poniższej tabeli opisano właściwości konfiguracji wyzwalacza ustawione w pliku function.json , które różnią się wersją środowiska uruchomieniowego.

W poniższej tabeli opisano właściwości konfiguracji powiązania ustawione w pliku function.json .

właściwość function.json opis
type Wymagane — musi być ustawiona na httpTriggerwartość .
direction Wymagane — musi być ustawiona na inwartość .
name Wymagane — nazwa zmiennej używana w kodzie funkcji dla treści żądania lub żądania.
authLevel Określa, jakie klucze, jeśli istnieją, muszą być obecne w żądaniu, aby wywołać funkcję. Aby uzyskać obsługiwane wartości, zobacz Poziom autoryzacji.
Metody Tablica metod HTTP, na które odpowiada funkcja. Jeśli nie zostanie określony, funkcja odpowiada na wszystkie metody HTTP. Zobacz Dostosowywanie punktu końcowego HTTP.
Trasy Definiuje szablon trasy, kontrolując, na które adresy URL żądań odpowiada funkcja. Wartość domyślna, jeśli żadna z nich nie jest podana, to <functionname>. Aby uzyskać więcej informacji, zobacz dostosowywanie punktu końcowego HTTP.

Użycie

W tej sekcji opisano sposób konfigurowania powiązania funkcji wyzwalacza HTTP.

Adnotacja HttpTrigger powinna być stosowana do parametru metody jednego z następujących typów:

  • HttpRequestMessage<T>.
  • Wszelkie natywne typy języka Java, takie jak int, String, byte[].
  • Wartości dopuszczane wartości null przy użyciu opcji Opcjonalne.
  • Dowolny zwykły typ obiektu Java (POJO).

Ładunek

Typ danych wejściowych wyzwalacza jest zadeklarowany jako jeden z następujących typów:

Type Opis
HttpRequest Użycie tego typu wymaga skonfigurowania aplikacji z integracją ASP.NET Core na platformie .NET Isolated.
Zapewnia to pełny dostęp do obiektu żądania i ogólnego obiektu HttpContext.
HttpRequestData Projekcja obiektu żądania.
Typ niestandardowy Gdy treść żądania to JSON, środowisko uruchomieniowe podejmie próbę przeanalizowania go w celu ustawienia właściwości obiektu.

Gdy parametr wyzwalacza jest parametrem HttpRequestDataHttpRequest, typy niestandardowe mogą być również powiązane z dodatkowymi parametrami przy użyciu polecenia Microsoft.Azure.Functions.Worker.Http.FromBodyAttribute. Użycie tego atrybutu wymaga Microsoft.Azure.Functions.Worker.Extensions.Http wersji 3.1.0 lub nowszej. Należy pamiętać, że jest to inny typ niż podobny atrybut w Microsoft.AspNetCore.Mvcsystemie , a w przypadku korzystania z integracji ASP.NET Core potrzebny jest w pełni kwalifikowany odwołanie lub using instrukcja. W poniższym przykładzie pokazano, jak za pomocą atrybutu pobrać tylko zawartość treści, a jednocześnie mieć dostęp do pełnej HttpRequestzawartości przy użyciu integracji z platformą 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);
}

Dostosowywanie punktu końcowego HTTP

Domyślnie podczas tworzenia funkcji wyzwalacza HTTP funkcja jest adresowalna przy użyciu trasy formularza:

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

Tę trasę można dostosować przy użyciu właściwości opcjonalnej route w powiązaniu wejściowym wyzwalacza HTTP. Możesz użyć dowolnego ograniczenia trasy internetowego interfejsu API z parametrami.

Poniższy kod funkcji akceptuje dwa parametry category i id w trasie i zapisuje odpowiedź przy użyciu obu parametrów.

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

Parametry trasy są definiowane przy użyciu route ustawienia HttpTrigger adnotacji. Poniższy kod funkcji akceptuje dwa parametry category i id w trasie i zapisuje odpowiedź przy użyciu obu parametrów.

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

Na przykład poniższy kod Języka TypeScript definiuje route właściwość wyzwalacza HTTP z dwoma parametrami category i id. Przykład odczytuje parametry z żądania i zwraca ich wartości w odpowiedzi.

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

Na przykład poniższy kod JavaScript definiuje route właściwość wyzwalacza HTTP z dwoma parametrami category i id. Przykład odczytuje parametry z żądania i zwraca ich wartości w odpowiedzi.

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

Na przykład poniższy kod definiuje route właściwość wyzwalacza HTTP z dwoma parametrami category i id:

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

Parametry trasy zadeklarowane w pliku function.json są dostępne jako właściwość $Request.Params obiektu.

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

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

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

Kontekst wykonywania funkcji jest uwidaczniony za pośrednictwem parametru zadeklarowanego jako func.HttpRequest. To wystąpienie umożliwia funkcji uzyskiwanie dostępu do parametrów trasy danych, wartości ciągu zapytania i metod, które umożliwiają zwracanie odpowiedzi HTTP.

Po zdefiniowaniu parametry trasy są dostępne dla funkcji przez wywołanie route_params metody .

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)

Korzystając z tej konfiguracji, funkcja jest teraz adresowalna z następującą trasą zamiast oryginalnej trasy.

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

Ta konfiguracja umożliwia kodowi funkcji obsługę dwóch parametrów w adresie, kategorii i identyfikatorze. Aby uzyskać więcej informacji na temat sposobu tokenizacji parametrów trasy w adresie URL, zobacz Routing w ASP.NET Core.

Domyślnie wszystkie trasy funkcji są poprzedzone interfejsem API. Możesz również dostosować lub usunąć prefiks przy użyciu extensions.http.routePrefix właściwości w pliku host.json . Poniższy przykład usuwa prefiks trasy interfejsu API przy użyciu pustego ciągu prefiksu w pliku host.json .

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

Używanie parametrów trasy

Parametry trasy, które zdefiniowały wzorzec funkcji route , są dostępne dla każdego powiązania. Jeśli na przykład masz trasę zdefiniowaną jako "route": "products/{id}" powiązanie magazynu tabel, może użyć wartości {id} parametru w konfiguracji powiązania.

Poniższa konfiguracja pokazuje, jak {id} parametr jest przekazywany do powiązania rowKey.

@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}"
}

Jeśli używasz parametrów trasy, element invoke_URL_template zostanie automatycznie utworzony dla funkcji. Klienci mogą użyć szablonu adresu URL, aby zrozumieć parametry, które muszą przekazać w adresie URL podczas wywoływania funkcji przy użyciu jej adresu URL. Przejdź do jednej z funkcji wyzwalanych przez protokół HTTP w witrynie Azure Portal i wybierz pozycję Pobierz adres URL funkcji.

Dostęp do invoke_URL_template obiektu można uzyskać programowo przy użyciu interfejsów API usługi Azure Resource Manager dla funkcji listy lub funkcji Get.

Strumienie HTTP (wersja zapoznawcza)

Teraz możesz przesyłać strumieniowo żądania do punktu końcowego HTTP i odpowiadać w aplikacjach funkcji Node.js w wersji 4. Aby uzyskać więcej informacji, zobacz Strumienie HTTP.

Praca z tożsamościami klientów

Jeśli aplikacja funkcji korzysta z uwierzytelniania/autoryzacji usługi App Service, możesz wyświetlić informacje o uwierzytelnionych klientach z kodu. Te informacje są dostępne jako nagłówki żądań wstrzykiwane przez platformę.

Te informacje można również odczytać z danych powiązania. Ta funkcja jest dostępna tylko dla środowiska uruchomieniowego usługi Functions w wersji 2.x i nowszej. Jest ona również obecnie dostępna tylko dla języków platformy .NET.

Informacje dotyczące uwierzytelnionych klientów są dostępne jako claimsPrincipal, który jest dostępny jako część kontekstu żądania, jak pokazano w poniższym przykładzie:

Uwierzytelniony użytkownik jest dostępny za pośrednictwem nagłówków HTTP.

Uwierzytelniony użytkownik jest dostępny za pośrednictwem nagłówków HTTP.

Poziom autoryzacji

Poziom autoryzacji to wartość ciągu wskazująca rodzaj klucza autoryzacji wymaganego do uzyskania dostępu do punktu końcowego funkcji. W przypadku funkcji wyzwalanej przez protokół HTTP poziom autoryzacji może być jedną z następujących wartości:

Wartość poziomu opis
Anonimowy Klucz interfejsu API nie jest wymagany. Jest to wartość domyślna, gdy poziom nie jest specjalnie ustawiony.
Funkcja Wymagany jest klucz interfejsu API specyficzny dla funkcji.
Admin Klucz główny jest wymagany.
Wartość poziomu opis
Anonimowy Klucz interfejsu API nie jest wymagany.
Funkcja Wymagany jest klucz interfejsu API specyficzny dla funkcji. Jest to wartość domyślna, gdy poziom nie jest specjalnie ustawiony.
Admin Klucz główny jest wymagany.

Klucze dostępu funkcji

Funkcje umożliwiają używanie kluczy, aby utrudnić dostęp do punktów końcowych funkcji HTTP podczas programowania. Jeśli poziom dostępu HTTP w funkcji wyzwalanej przez protokół HTTP jest ustawiony na anonymouswartość , żądania muszą zawierać klucz dostępu interfejsu API w żądaniu.

Klucze zapewniają domyślny mechanizm zabezpieczeń, ale warto rozważyć inne opcje zabezpieczania punktu końcowego HTTP w środowisku produkcyjnym. Na przykład nie jest to dobre rozwiązanie do rozpowszechniania udostępnionego wpisu tajnego w aplikacjach publicznych. Jeśli funkcja jest wywoływana z klienta publicznego, warto rozważyć zaimplementowanie innego mechanizmu zabezpieczeń. Aby dowiedzieć się więcej, zobacz Zabezpieczanie punktu końcowego HTTP w środowisku produkcyjnym.

Po odnowieniu wartości klucza funkcji należy ręcznie ponownie rozsyłać zaktualizowane wartości klucza do wszystkich klientów wywołujących funkcję.

Zakresy autoryzacji (poziom funkcji)

Istnieją dwa zakresy dostępu dla kluczy na poziomie funkcji:

  • Funkcja: Te klucze mają zastosowanie tylko do określonych funkcji, w których są zdefiniowane. W przypadku użycia jako klucza interfejsu API te zezwalają tylko na dostęp do tej funkcji.

  • Host: klucze z zakresem hosta mogą służyć do uzyskiwania dostępu do wszystkich funkcji w aplikacji funkcji. Jeśli jest używany jako klucz interfejsu API, umożliwiają one dostęp do dowolnej funkcji w aplikacji funkcji.

Każdy klucz jest nazwany jako odwołanie i istnieje klucz domyślny (o nazwie "default") na poziomie funkcji i hosta. Klucze funkcji mają pierwszeństwo przed kluczami hosta. Gdy dwa klucze są zdefiniowane o tej samej nazwie, klucz funkcji jest zawsze używany.

Klucz główny (poziom administratora)

Każda aplikacja funkcji ma również klucz hosta na poziomie administratora o nazwie _master. Oprócz zapewnienia dostępu na poziomie hosta do wszystkich funkcji w aplikacji klucz główny zapewnia również dostęp administracyjny do interfejsów API REST środowiska uruchomieniowego. Nie można odwołać tego klucza. Po ustawieniu poziomu admindostępu żądania muszą używać klucza głównego. Każdy inny klucz powoduje niepowodzenie dostępu.

Uwaga

Ze względu na podniesione uprawnienia w aplikacji funkcji przyznane przez klucz główny nie należy udostępniać tego klucza innym firmom ani rozpowszechniać go w natywnych aplikacjach klienckich. Zachowaj ostrożność podczas wybierania poziomu dostępu administratora.

Uzyskiwanie kluczy

Klucze są przechowywane jako część aplikacji funkcji na platformie Azure i są szyfrowane w spoczynku. Aby wyświetlić klucze, utwórz nowe lub przerzuć klucze do nowych wartości, przejdź do jednej z funkcji wyzwalanych przez protokół HTTP w witrynie Azure Portal i wybierz pozycję Klucze funkcji.

Możesz również zarządzać kluczami hosta. Przejdź do aplikacji funkcji w witrynie Azure Portal i wybierz pozycję Klucze aplikacji.

Klucze funkcji i hosta można uzyskać programowo przy użyciu interfejsów API usługi Azure Resource Manager. Istnieją interfejsy API do wyświetlania listy kluczy funkcji i list kluczy hosta, a w przypadku korzystania z miejsc wdrożenia równoważne interfejsy API to Miejsce kluczy funkcji listy i Miejsce kluczy hosta listy.

Możesz również programowo utworzyć nową funkcję i klucze hosta przy użyciu interfejsu API tworzenia lub aktualizowania wpisu tajnego funkcji, tworzenia lub aktualizowania wpisu tajnego funkcji, tworzenia lub aktualizowania klucza tajnego hosta oraz tworzenia lub aktualizowania interfejsów API miejsca wpisu tajnego hosta.

Klucze funkcji i hosta można usunąć programowo przy użyciu interfejsów API usuń wpis tajny funkcji, usuń miejsce wpisu tajnego funkcji, usuń wpis tajny hosta i usuń interfejsy API miejsca wpisu tajnego hosta.

Możesz również użyć starszych interfejsów API zarządzania kluczami, aby uzyskać klucze funkcji, ale zamiast tego zaleca się używanie interfejsów API usługi Azure Resource Manager.

Autoryzacja klucza interfejsu API

Większość szablonów wyzwalaczy HTTP wymaga klucza interfejsu API w żądaniu. W związku z tym żądanie HTTP zwykle wygląda jak następujący adres URL:

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

Klucz można uwzględnić w zmiennej ciągu zapytania o nazwie code, jak pokazano powyżej. Można go również uwzględnić w nagłówku x-functions-key HTTP. Wartość klucza może być dowolnym kluczem funkcji zdefiniowanym dla funkcji lub dowolnym kluczem hosta.

Możesz zezwolić na żądania anonimowe, które nie wymagają kluczy. Można również wymagać użycia klucza głównego. Domyślny poziom autoryzacji można zmienić przy użyciu authLevel właściwości w formacie JSON powiązania. Aby uzyskać więcej informacji, zobacz Wyzwalacz — konfiguracja.

Uwaga

W przypadku lokalnego uruchamiania funkcji autoryzacja jest wyłączona niezależnie od określonego ustawienia poziomu autoryzacji. Po opublikowaniu authLevel na platformie Azure ustawienie w wyzwalaczu jest wymuszane. Klucze są nadal wymagane w przypadku uruchamiania lokalnego w kontenerze.

Zabezpieczanie punktu końcowego HTTP w środowisku produkcyjnym

Aby w pełni zabezpieczyć punkty końcowe funkcji w środowisku produkcyjnym, należy rozważyć zaimplementowanie jednej z następujących opcji zabezpieczeń na poziomie aplikacji funkcji. W przypadku korzystania z jednej z tych metod zabezpieczeń na poziomie aplikacji funkcji należy ustawić poziom autoryzacji funkcji wyzwalanej przez protokół HTTP na anonymouswartość .

Włączanie uwierzytelniania/autoryzacji usługi App Service

Platforma App Service umożliwia uwierzytelnianie klientów przy użyciu identyfikatora Entra firmy Microsoft i kilku dostawców tożsamości innych firm. Ta strategia umożliwia zaimplementowanie niestandardowych reguł autoryzacji dla funkcji i pracę z informacjami o użytkowniku z poziomu kodu funkcji. Aby dowiedzieć się więcej, zobacz Uwierzytelnianie i autoryzacja w usłudze aplikacja systemu Azure i Praca z tożsamościami klientów.

Uwierzytelnianie żądań przy użyciu usługi Azure API Management (APIM)

Usługa APIM oferuje różne opcje zabezpieczeń interfejsu API dla żądań przychodzących. Aby dowiedzieć się więcej, zobacz Zasady uwierzytelniania usługi API Management. Za pomocą usługi APIM możesz skonfigurować aplikację funkcji tak, aby akceptowała żądania tylko z adresu IP wystąpienia usługi APIM. Aby dowiedzieć się więcej, zobacz Ograniczenia adresów IP.

Wdrażanie aplikacji funkcji w izolacji

środowisko aplikacja systemu Azure Service Environment (ASE) udostępnia dedykowane środowisko hostingu, w którym można uruchamiać funkcje. Środowisko ASE umożliwia skonfigurowanie pojedynczej bramy frontonu, której można użyć do uwierzytelniania wszystkich żądań przychodzących. Aby uzyskać więcej informacji, zobacz Konfigurowanie zapory aplikacji internetowej (WAF) dla środowiska App Service Environment.

Elementy webhook

Uwaga

Tryb elementu webhook jest dostępny tylko dla wersji 1.x środowiska uruchomieniowego usługi Functions. Ta zmiana została wprowadzona w celu zwiększenia wydajności wyzwalaczy HTTP w wersji 2.x i nowszej.

W wersji 1.x szablony elementów webhook zapewniają dodatkową walidację ładunków elementów webhook. W wersji 2.x i nowszej podstawowy wyzwalacz HTTP nadal działa i jest zalecanym podejściem dla elementów webhook.

Typ elementu webhook

Właściwość webHookType powiązania wskazuje typ elementu webhook obsługiwanego przez funkcję, co również określa obsługiwany ładunek. Typ elementu webhook może być jedną z następujących wartości:

Wartość typu opis
genericJson Punkt końcowy elementu webhook ogólnego przeznaczenia bez logiki dla określonego dostawcy. To ustawienie ogranicza żądania tylko do żądań korzystających z protokołu HTTP POST i typu application/json zawartości.
github Funkcja odpowiada na elementy webhook usługi GitHub. Nie używaj authLevel właściwości z elementami webhook usługi GitHub.
slack Funkcja odpowiada na elementy webhook usługi Slack. Nie używaj authLevel właściwości z elementami webhook usługi Slack.

Podczas ustawiania webHookType właściwości nie należy również ustawiać methods właściwości powiązania.

GitHub webhooks (Elementy webhook usługi GitHub)

Aby odpowiedzieć na elementy webhook usługi GitHub, najpierw utwórz funkcję za pomocą wyzwalacza HTTP i ustaw właściwość webHookType na githubwartość . Następnie skopiuj jego adres URL i klucz interfejsu API do strony Dodawanie elementu webhook repozytorium GitHub.

Screenshot that shows how to add a webhook for your function.

Elementy webhook usługi Slack

Element webhook usługi Slack generuje token zamiast umożliwiać jego określenie, dlatego należy skonfigurować klucz specyficzny dla funkcji przy użyciu tokenu z usługi Slack. Zobacz Klucze autoryzacji.

Elementy webhook i klucze

Autoryzacja elementu webhook jest obsługiwana przez składnik odbiornika elementu webhook, część wyzwalacza HTTP, a mechanizm różni się w zależności od typu elementu webhook. Każdy mechanizm opiera się na kluczu. Domyślnie używany jest klucz funkcji o nazwie "default". Aby użyć innego klucza, skonfiguruj dostawcę elementu webhook, aby wysłać nazwę klucza z żądaniem w jeden z następujących sposobów:

  • Ciąg zapytania: dostawca przekazuje nazwę klucza w parametrze clientid ciągu zapytania, takim jak https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?clientid=<KEY_NAME>.
  • Nagłówek żądania: dostawca przekazuje nazwę klucza w nagłówku x-functions-clientid .

Typy zawartości

Przekazywanie danych binarnych i danych formularza do funkcji innej niż C# wymaga użycia odpowiedniego nagłówka typu zawartości. Obsługiwane typy zawartości obejmują octet-stream dane binarne i typy wieloczęściowe.

Znane problemy

W funkcjach innych niż C# żądania wysyłane z typem image/jpegstring zawartości powoduje przekazanie wartości do funkcji. W takich przypadkach można ręcznie przekonwertować string wartość na tablicę bajtów, aby uzyskać dostęp do nieprzetworzonych danych binarnych.

Limity

Długość żądania HTTP jest ograniczona do 100 MB (104 857 600 bajtów), a długość adresu URL jest ograniczona do 4 KB (4096 bajtów). Te limity są określane przez httpRuntime element pliku Web.config środowiska uruchomieniowego.

Jeśli funkcja używająca wyzwalacza HTTP nie zostanie ukończona w ciągu 230 sekund, usługa Azure Load Balancer upłynął limit czasu i zwróci błąd HTTP 502. Funkcja będzie nadal działać, ale nie będzie mogła zwrócić odpowiedzi HTTP. W przypadku długotrwałych funkcji zalecamy stosowanie wzorców asynchronicznych i zwracanie lokalizacji, w której można wysłać polecenie ping do stanu żądania. Aby uzyskać informacje o tym, jak długo można uruchomić funkcję, zobacz Skalowanie i hostowanie — plan zużycie.

Następne kroki