Azure Functions HTTP 觸發程序

發行項
04/07/2024

HTTP 觸發程式可讓您使用 HTTP 要求叫用函式。您可以使用 HTTP 觸發程式來建置無伺服器 API 並回應 Webhook。

HTTP 觸發函式的預設傳回值為：

HTTP 204 No Content 函式 2.x 和更新版本中的空白主體
HTTP 200 OK 函式 1.x 中的空白本文

若要修改 HTTP 回應，請設定輸出系結。

如需 HTTP 系結的詳細資訊，請參閱概觀和輸出系結參考。

提示

如果您打算使用 HTTP 或 WebHook 的繫結，請做好規劃，以免因為 HttpClient 具現化不當而耗盡連接埠。如需詳細資訊，請參閱如何管理 Azure Functions 中的連線。

重要

本文使用索引標籤來支援多個版本的Node.js程序設計模型。 v4 模型已正式推出，旨在為 JavaScript 和 TypeScript 開發人員提供更靈活的直覺式體驗。如需 v4 模型運作方式的詳細資訊，請參閱 Azure Functions Node.js開發人員指南。若要深入瞭解 v3 與 v4 之間的差異，請參閱移轉指南。

Azure Functions 支援兩種適用於 Python 的程式設計模型。您定義系結的方式取決於您所選擇的程式設計模型。

Python v2 程式設計模型可讓您直接在 Python 函式程式代碼中使用裝飾項目來定義系結。如需詳細資訊，請參閱 Python 開發人員指南。

本文支援這兩種程序設計模型。

範例

您可以使用下列其中一種 C# 模式來建立 C# 函式：

隔離的背景工作模型：在與運行時間隔離的背景工作進程中執行的已編譯 C# 函式。需要隔離的背景工作進程，才能支援在 LTS 和非 LTS 版本 .NET 和 .NET Framework 上執行的 C# 函式。隔離背景工作進程函式的延伸模組會使用 Microsoft.Azure.Functions.Worker.Extensions.* 命名空間。
同進程模型：在與 Functions 運行時間相同的進程中執行的已編譯 C# 函式。在此模型的變化中，函式可以使用 C# 腳本來執行，主要支援 C# 入口網站編輯。進程內函式的延伸模組會使用 Microsoft.Azure.WebJobs.Extensions.* 命名空間。

重要

支援將於 2026 年 11 月 10 日結束進程模型。強烈建議您將應用程式移轉至隔離的背景工作模型，以取得完整支援。

本文中的程式代碼預設為 .NET Core 語法，用於 Functions 2.x 版和更新版本。如需 1.x 語法的資訊，請參閱 1.x 函式範本。

隔離式背景工作角色模型
內含式模型

下列範例示範使用 .NET Isolated 中的 ASP.NET Core 整合，以 IActionResult 傳回 “hello， world” 回應的 HTTP 觸發程式：

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

下列範例顯示 HTTP 觸發程式，此觸發程式會以 HttpResponseData 物件的形式傳回「hello world」回應：

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

下列範例示範在查詢字串或 HTTP 要求主體中尋找name參數的 C# 函式。請注意，傳回值用於輸出系結，但不需要傳回值屬性。

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

本區段包含下列範例：

從查詢字串讀取參數
從 POST 要求讀取本文
從路由讀取參數
從 POST 要求讀取 POJO 本文

下列範例顯示 HTTP 觸發程式系結。

從查詢字串讀取參數

此範例會從查詢字串讀取名為 id的參數，並用它來建置傳回給用戶端的 JSON 檔，其內容類型為 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();
    }
}

從 POST 要求讀取本文

此範例會以讀取 POST 要求的本文， String並使用它來建置傳回給用戶端的 JSON 檔，其內容類型為 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();
        }
    }

從路由讀取參數

此範例會從路由路徑讀取名為的強制參數和選擇性參數idname，並使用它們來建置傳回給用戶端的 JSON 檔案，其內容類型為 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();
    }
}

從 POST 要求讀取 POJO 本文

以下是在此範例中參考的 ToDoItem 類別程式代碼：


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

此範例會讀取 POST 要求的本文。要求本文會自動還原串行化為 ToDoItem 物件，並傳回給用戶端，其內容類型為 application/json。參數 ToDoItem 是由 Functions 執行時間串行化，因為它會指派給 body 類別的 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();
    }
}

模型 v4
模型 v3

下列範例顯示 HTTP 觸發程式 TypeScript 函式。函式會尋找 name 參數，其位於查詢字串或 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,
});

模型 v4
模型 v3

下列範例顯示 HTTP 觸發程式 JavaScript 函式。函式會尋找 name 參數，其位於查詢字串或 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}!` };
    },
});

下列範例示範function.json檔案中的觸發程式系結，以及使用系結的 JavaScript 函式。 函式會尋找 name 參數，其位於查詢字串或 HTTP 要求的主體。

以下是 function.json 檔案：

{
    "disabled": false,    
    "bindings": [
        {
            "authLevel": "function",
            "type": "httpTrigger",
            "direction": "in",
            "name": "req"
        },
        {
            "type": "http",
            "direction": "out",
            "name": "res"
        }
    ]
}

組態區段說明這些屬性。

以下是 JavaScript 程式代碼：

module.exports = async function(context, req) {
    context.log('Node.js HTTP trigger function processed a request. RequestUri=%s', req.originalUrl);

    if (req.query.name || (req.body && req.body.name)) {
        context.res = {
            // status defaults to 200 */
            body: "Hello " + (req.query.name || req.body.name)
        };
    }
    else {
        context.res = {
            status: 400,
            body: "Please pass a name on the query string or in the request body"
        };
    }
};

下列範例顯示function.json檔案和PowerShell函式中的觸發程式系結。函式會尋找 name 參數，其位於查詢字串或 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
})

下列範例顯示觸發程式系結和使用系結的 Python 函式。函式會尋找 name 參數，其位於查詢字串或 HTTP 要求的主體。此範例取決於您使用的是 v1 或 v2 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
        )

以下是 function.json 檔案：

{
    "scriptFile": "__init__.py",
    "disabled": false,    
    "bindings": [
        {
            "authLevel": "function",
            "type": "httpTrigger",
            "direction": "in",
            "name": "req"
        },
        {
            "type": "http",
            "direction": "out",
            "name": "$return"
        }
    ]
}

組態區段說明這些屬性。

以下是 Python 程式代碼：

import logging
import azure.functions as func


def main(req: func.HttpRequest) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request.')

    name = req.params.get('name')
    if not name:
        try:
            req_body = req.get_json()
        except ValueError:
            pass
        else:
            name = req_body.get('name')

    if name:
        return func.HttpResponse(f"Hello {name}!")
    else:
        return func.HttpResponse(
            "Please pass a name on the query string or in the request body",
            status_code=400
        )

屬性

進程內和隔離的背景工作進程 C# 連結庫都會使用 HttpTriggerAttribute 來定義觸發程式系結。 C# 文稿會改用function.json組態檔，如 C# 腳本指南中所述。

隔離式背景工作角色模型
內含式模型

在隔離的背景工作進程函式應用程式中，支援 HttpTriggerAttribute 下列參數：

參數	描述
AuthLevel	會判斷要求中必須存在哪些金鑰 (若有的話) 才能叫用函式。如需支援的值，請參閱授權層級。
方法	函數將回應的 HTTP 方法陣列。如果未指定，函式將會回應所有的 HTTP 方法。請參閱自訂 HTTP 端點。
路由	會定義路由範本，從而控制函式所要回應的要求 URL。如果沒有提供任何值，預設值為 `<functionname>`。如需詳細資訊，請參閱自訂 HTTP 端點。

在進程內函式中 HttpTriggerAttribute ，支援下列參數：

參數	描述
AuthLevel	會判斷要求中必須存在哪些金鑰 (若有的話) 才能叫用函式。如需支援的值，請參閱授權層級。
方法	函數將回應的 HTTP 方法陣列。如果未指定，函式將會回應所有的 HTTP 方法。請參閱自訂 HTTP 端點。
路由	會定義路由範本，從而控制函式所要回應的要求 URL。如果沒有提供任何值，預設值為 `<functionname>`。如需詳細資訊，請參閱自訂 HTTP 端點。
WebHookType	只有針對 1.x 版執行階段才有支援。會設定 HTTP 觸發程序作為指定提供者的 webhook 接收器。如需支援的值，請參閱 WebHook 類型。

裝飾項目

僅適用於 Python v2 程式設計模型。

針對使用裝飾項目定義的 Python v2 函式，觸發程式的下列屬性定義於 route 裝飾專案中，這會新增 HttpTrigger 和 HttpOutput 系結：

屬性	說明
`route`	HTTP 端點的路由。如果為 None，則如果存在或使用者定義的 Python 函式名稱，則會將其設定為函式名稱。
`trigger_arg_name`	HttpRequest 的自變數名稱。預設值為『req』。
`binding_arg_name`	HttpResponse 的自變數名稱。預設值為『$return』。
`methods`	函式回應之 HTTP 方法的 Tuple。
`auth_level`	會判斷要求中必須存在哪些金鑰 (若有的話) 才能叫用函式。

如需使用 function.json 定義的 Python 函式，請參閱組態一節。

註釋

在 Java 函式執行時間連結庫中，使用支援下列設定的 HttpTrigger 註釋：

組態

僅適用於 Python v1 程式設計模型。

模型 v4
模型 v3

下表說明您可以在傳遞至 app.http() 方法的物件options上設定的屬性。

屬性	說明
authLevel	會判斷要求中必須存在哪些金鑰 (若有的話) 才能叫用函式。如需支援的值，請參閱授權層級。
方法	函數將回應的 HTTP 方法陣列。如果未指定，函式將會回應所有的 HTTP 方法。請參閱自訂 HTTP 端點。
route	會定義路由範本，從而控制函式所要回應的要求 URL。如果沒有提供任何值，預設值為 `<functionname>`。如需詳細資訊，請參閱自訂 HTTP 端點。

下表說明您在 function.json 檔案中設定的繫結設定屬性。

function.json 屬性	描述
type	必要項目 - 必須設定為 `httpTrigger`。
direction	必要項目 - 必須設定為 `in`。
name	必要項目 - 函式程式碼中用於要求或要求主體的變數名稱。
authLevel	會判斷要求中必須存在哪些金鑰 (若有的話) 才能叫用函式。如需支援的值，請參閱授權層級。
方法	函數將回應的 HTTP 方法陣列。如果未指定，函式將會回應所有的 HTTP 方法。請參閱自訂 HTTP 端點。
route	會定義路由範本，從而控制函式所要回應的要求 URL。如果沒有提供任何值，預設值為 `<functionname>`。如需詳細資訊，請參閱自訂 HTTP 端點。

下表說明您在 function.json 檔案中設定的觸發程式組態屬性，其與運行時間版本不同。

Functions 2.x+
Functions 1.x

下表說明您在 function.json 檔案中設定的繫結設定屬性。

function.json 屬性	描述
type	必要項目 - 必須設定為 `httpTrigger`。
direction	必要項目 - 必須設定為 `in`。
name	必要項目 - 函式程式碼中用於要求或要求主體的變數名稱。
authLevel	會判斷要求中必須存在哪些金鑰 (若有的話) 才能叫用函式。如需支援的值，請參閱授權層級。
方法	函數將回應的 HTTP 方法陣列。如果未指定，函式將會回應所有的 HTTP 方法。請參閱自訂 HTTP 端點。
route	會定義路由範本，從而控制函式所要回應的要求 URL。如果沒有提供任何值，預設值為 `<functionname>`。如需詳細資訊，請參閱自訂 HTTP 端點。

下表說明您在 function.json 檔案中設定的繫結設定屬性。

function.json 屬性	描述
type	必要項目 - 必須設定為 `httpTrigger`。
direction	必要項目 - 必須設定為 `in`。
name	必要項目 - 函式程式碼中用於要求或要求主體的變數名稱。
authLevel	會判斷要求中必須存在哪些金鑰 (若有的話) 才能叫用函式。如需支援的值，請參閱授權層級。
方法	函數將回應的 HTTP 方法陣列。如果未指定，函式將會回應所有的 HTTP 方法。請參閱自訂 HTTP 端點。
route	會定義路由範本，從而控制函式所要回應的要求 URL。如果沒有提供任何值，預設值為 `<functionname>`。如需詳細資訊，請參閱自訂 HTTP 端點。
webHookType	會設定 HTTP 觸發程序作為指定提供者的 webhook 接收器。如需支援的值，請參閱 WebHook 類型。

使用方式

本節詳細說明如何設定 HTTP 觸發程式函式系結。

HttpTrigger 註釋應該套用至下列其中一種類型的方法參數：

HttpRequestMessage<T>。
任何原生 Java 類型，例如 int、String、byte[]。
使用選擇性的可為 Null 值。
任何純舊 Java 物件（POJO）類型。

觸發程式輸入類型宣告為下列其中一種類型：

類型	描述
HttpRequest	使用此類型時，應用程式必須在 .NET Isolated 中使用 ASP.NET Core 整合來設定。這可讓您完整存取要求對象和整體 HttpContext。
HttpRequestData	要求物件的投影。
自訂類型	當要求的主體為 JSON 時，運行時間會嘗試剖析它來設定物件屬性。

當觸發程式參數是 HttpRequestDataHttpRequest時，自定義類型也可以使用系結至其他參數 Microsoft.Azure.Functions.Worker.Http.FromBodyAttribute。使用此屬性需要 Microsoft.Azure.Functions.Worker.Extensions.Http 3.1.0 版或更新版本。請注意，這與中的 Microsoft.AspNetCore.Mvc類似屬性不同，而且在使用 ASP.NET Core 整合時，您需要完整的參考或 using 語句。下列範例示範如何使用屬性來取得主體內容，同時仍可使用 ASP.NET Core 整合來存取完整 HttpRequest內容：

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

自訂 HTTP 端點

根據預設，當您為 HTTP 觸發程式建立函式時，函式可以使用格式的路由來尋址：

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

您可以使用 HTTP 觸發程式輸入系結上的選擇性 route 屬性來自定義此路由。您可以使用任何 Web API 路由條件約束搭配您的參數。

隔離式背景工作角色模型
內含式模型

下列函式程式代碼會接受路由中的兩個參數 category ， id 並使用這兩個參數寫入回應。

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

下列 C# 函式程式代碼會在路由中接受兩個參數 category ， id 並使用這兩個參數寫入回應。

[FunctionName("Function1")]
public static IActionResult Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = "products/{category:alpha}/{id:int?}")] HttpRequest req,
string category, int? id, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    var message = String.Format($"Category: {category}, ID: {id}");
    return (ActionResult)new OkObjectResult(message);
}

路由參數是使用 route 註釋的 HttpTrigger 設定來定義。下列函式程式代碼會接受路由中的兩個參數 category ， id 並使用這兩個參數寫入回應。

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

模型 v4
模型 v3

例如，下列 TypeScript 程式代碼會使用兩個 route 參數 categoryid和來定義 HTTP 觸發程式的屬性。此範例會從要求讀取參數，並在響應中傳回其值。

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

模型 v4
模型 v3

例如，下列 JavaScript 程式代碼會使用兩個 route 參數 categoryid和來定義 HTTP 觸發程式的屬性。此範例會從要求讀取參數，並在響應中傳回其值。

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

例如，下列 function.json 檔案會定義具有兩個 route 參數之 HTTP 觸發程式的屬性， category 以及 id：

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

Functions 運行時間會從 context 物件提供要求本文。下列範例示範如何從 context.bindingData讀取路由參數。

module.exports = async function (context, req) {

    var category = context.bindingData.category;
    var id = context.bindingData.id;
    var message = `Category: ${category}, ID: ${id}`;

    context.res = {
        body: message;
    }
}

例如，下列程式代碼會使用兩個 route 參數定義 HTTP 觸發程式的屬性， category 以及 id：

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

在function.json檔案中：

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

function.json檔案中宣告的$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
})

函式執行內容會透過宣告為 func.HttpRequest的參數公開。這個實例可讓函式存取數據路由參數、查詢字串值和方法，讓您傳回 HTTP 回應。

定義之後，路由參數可藉由呼叫 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)

使用此組態，函式現在可以使用下列路由來尋址，而不是原始路由。

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

此組態可讓函式程式代碼支援位址、類別和 識別碼中的兩個參數。如需如何在 URL 中標記路由參數的詳細資訊，請參閱 ASP.NET Core 中的路由。

根據預設，所有函式路由都會加上 api。您也可以使用 extensions.http.routePrefix host.json 檔案中的屬性來自定義或移除前置詞。下列範例會使用 host.json 檔案中前置詞的空字串來移除 api 路由前置詞。

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

使用路由參數

定義函式模式的 route 路由參數可供每個系結使用。例如，如果您有定義為 "route": "products/{id}" 的路由，數據表記憶體系結就可以在系結組態中使用參數的值 {id} 。

下列群組態顯示如何將 {id} 參數傳遞至係結的 rowKey。

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

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

模型 v4
模型 v3

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

模型 v4
模型 v3

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",
    "connection": "MyStorageConnectionAppSetting",
    "partitionKey": "products",
    "tableName": "products",
    "rowKey": "{id}"
}

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

當您使用路由參數時， invoke_URL_template 會自動為您的函式建立。您的用戶端可以使用 URL 範本來瞭解使用其 URL 呼叫函式時，需要傳入 URL 的參數。流覽至 Azure 入口網站中的其中一個 HTTP 觸發函式，然後選取 [取得函式 URL]。

您可以使用 List Functions 或 Get Function 的 Azure Resource Manager API，以程式設計方式存取 invoke_URL_template 。

HTTP 資料流（預覽）

您現在可以在 v4 函式應用程式中串流對 HTTP 端點的要求和回應Node.js。如需詳細資訊，請參閱 HTTP 數據流。

使用用戶端身分識別

如果您的函式應用程式使用 App Service 驗證/授權，您可以從程式代碼檢視已驗證客戶端的相關信息。此資訊會以平臺插入的要求標頭的形式提供。

您也可以從系結數據讀取這項資訊。此功能僅適用於 2.x 和更新版本中的 Functions 執行時間。它目前也僅適用於 .NET 語言。

有關已驗證客戶端的資訊可做為 ClaimsPrincipal 提供，該宣告可作為要求內容的一部分，如下列範例所示：

隔離式背景工作角色模型
內含式模型

已驗證的用戶可透過 HTTP 標頭取得。

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

或者，ClaimsPrincipal 可以直接包含在函式簽章中做為其他參數：

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

已驗證的用戶可透過 HTTP 標頭取得。

授權等級

授權層級是字串值，指出存取函式端點所需的授權密鑰類型。針對 HTTP 觸發的函式，授權層級可以是下列其中一個值：

模型 v4
模型 v3

層級值	描述
anonymous	不需要 API 金鑰。當層級未特別設定時，這是預設值。
函數	需要函式特定的 API 金鑰。
admin	需要主要金鑰。

層級值	描述
anonymous	不需要 API 金鑰。
函數	需要函式特定的 API 金鑰。當層級未特別設定時，這是預設值。
admin	需要主要金鑰。

函式存取金鑰

Functions 可讓您使用金鑰來提高開發期間存取 HTTP 函式端點的困難度。除非 HTTP 觸發程序函數的 HTTP 存取層級設定為 anonymous，否則要求必須在要求中包含 API 存取金鑰。

雖然金鑰提供預設安全性機制，但您可能想要考慮其他選項來保護生產環境中的 HTTP 端點。例如，在公用應用程式中散發共用秘密並不是很好的做法。如果您的函式是從公用用戶端呼叫，您可能想要考慮實作另一個安全性機制。若要深入了解，請參閱在生產環境中保護 HTTP 端點。

當更新函式索引鍵值時，您必須手動將更新的索引鍵值重新散發給所有呼叫您函式的用戶端。

授權範圍 (函式層級)

函式層級金鑰有兩個存取範圍：

函式：這些金鑰僅適用於據以定義它們的特定函式。當做為 API 金鑰使用時，這些金鑰僅允許存取該函式。
主機：具有主機範圍的金鑰可用來存取函數應用程式內的所有函式。當做為 API 金鑰使用時，這些金鑰會允許存取函數應用程式中的任何函式。

每個金鑰均為具名以供參考，並且在函式和主機層級有一預設金鑰 (名稱為 "default")。函式金鑰的優先順序高於主機金鑰。當您使用相同的名稱來定義兩個金鑰時，一律會使用函式金鑰。

主要金鑰 (管理員層級)

每個函數應用程式也有一個名為 _master 的管理員層級主機金鑰。除了為應用程式中的所有函式提供主機層級存取之外，主要金鑰也會提供執行階段 REST API 的系統管理存取權。無法撤銷此金鑰。當您將存取層級設定為 admin 時，要求就必須使用主要金鑰；任何其他金鑰則會導致存取失敗。

警告

由於主要金鑰會在您的函數應用程式中授與提高的權限，因此您不應該與第三方共用此金鑰，或是在原生用戶端應用程式中散發它。當您選擇管理存取層級時，請務必謹慎。

取得金鑰

密鑰會儲存在 Azure 中做為函式應用程式的一部分，並在待用時加密。若要檢視金鑰、建立新的金鑰，或將金鑰變換至新的值，請流覽至 Azure 入口網站中的其中一個 HTTP 觸發函式，然後選取 [函式密鑰]。

您也可以管理主機金鑰。流覽至 Azure 入口網站中的函式應用程式，然後選取 [應用程式金鑰]。

您可以使用 Azure Resource Manager API，以程式設計方式取得函式和主機密鑰。有 API 可列出函式金鑰和列出主機金鑰，而使用部署位置時，對等 API 是 List 函式金鑰位置和列出主機金鑰位置。

您也可以使用建立或更新函式秘密、建立或更新函式秘密位置、建立或更新主機密碼和建立或更新主機秘密位置 API，以程式設計方式建立新的函式和主機密鑰。

您可以使用刪除函式秘密、刪除函式秘密位置、刪除主機密碼，以及刪除主機秘密位置 API，以程式設計方式刪除函式和主機密鑰。

您也可以使用舊版密鑰管理 API 來取得函式密鑰，但建議改用 Azure Resource Manager API。

API 金鑰授權

大部分的 HTTP 觸發程式範本都需要要求中的 API 金鑰。因此，您的 HTTP 要求通常看起來像下列 URL：

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

索引鍵可以包含在名為 code的查詢字串變數中，如上所示。它也可以包含在 HTTP 標頭中 x-functions-key 。索引鍵的值可以是針對函式定義的任何函式索引鍵，或任何主機密鑰。

您可以允許不需要金鑰的匿名要求。您也可以要求使用主要金鑰。您可以使用系結 JSON 中的屬性來變更預設授權層級 authLevel 。如需詳細資訊，請參閱觸發程式 - 組態。

注意

在本機執行函式時，不論指定的授權層級設定為何，都會停用授權。發佈至 Azure 之後， authLevel 會強制執行觸發程式中的設定。在容器中本機執行時，仍然需要密鑰。

保護生產環境中 HTTP 端點的安全

若要在生產環境中完全保護您的函式端點，您應該考慮實作下列其中一個函式應用層級安全性選項。使用下列其中一個函式應用層級安全性方法時，您應該將 HTTP 觸發的函式授權層級設定為 anonymous。

啟用 App Service 驗證/授權

App Service 平台可讓您使用 Microsoft Entra ID 及數個協力廠商身分識別提供者來驗證用戶端。您可以使用此策略為函式實作自訂授權規則，並可使用來自函式程式碼的使用者資訊。若要深入了解，請參閱 Azure App Service 中的驗證與授權和使用用戶端身分識別。

使用「Azure API 管理」(APIM) 來驗證要求

APIM 為傳入要求提供多種 API 安全性選項。若要深入了解，請參閱 API 管理驗證原則。備妥 APIM 之後，您可以設定讓函數應用程式只接受來自您 APIM 執行個體 IP 位址的要求。若要深入了解，請參閱 IP 位址限制。

以隔離方式部署函式應用程式

Azure App Service 環境 (ASE) 提供一個可供執行您函式的專用主控環境。 ASE 可讓您設定一個單一前端閘道，可用來驗證所有傳入要求。如需詳細資訊，請參閱設定 App Service Environment 的 Web 應用程式防火牆 (WAF)。

Webhooks

注意

Webhook 模式僅適用於 Functions 運行時間 1.x 版。這項變更可改善 2.x 版和更新版本中 HTTP 觸發程式的效能。

在 1.x 版中，Webhook 範本會提供 Webhook 承載的額外驗證。在 2.x 版和更新版本中，基底 HTTP 觸發程式仍可運作，而且是 Webhook 的建議方法。

WebHook 類型

如果函式支援的 Webhook，系 webHookType 結屬性會指出型別，這也會指定支持的承載。 Webhook 類型可以是下列其中一個值：

類型值	描述
`genericJson`	一般用途的 Webhook 端點，沒有特定提供者的邏輯。此設定只會將要求限制為使用 HTTP POST 和內容類型的要求 `application/json` 。
`github`	函式會回應 GitHub Webhook。請勿搭配 `authLevel` GitHub Webhook 使用屬性。
`slack`	函式會回應 Slack Webhook。請勿搭配 `authLevel` Slack Webhook 使用屬性。

設定 webHookType 屬性時，請勿在系結上設定 methods 屬性。

GitHub Webhook $英文$

若要回應 GitHub Webhook，請先使用 HTTP 觸發程式建立函式，然後將 webHookType 屬性設定為 github。然後將其 URL 和 API 金鑰 複製到 GitHub 存放庫的 [新增 Webhook ] 頁面。

顯示如何為您的函式新增 Webhook 的螢幕快照。

Slack Webhook

Slack Webhook 會為您產生令牌，而不是讓您指定令牌，因此您必須使用 Slack 的令牌來設定函式特定密鑰。請參閱授權金鑰。

Webhook 和金鑰

Webhook 授權是由 Webhook 接收者元件、HTTP 觸發程式的一部分來處理，而機制會根據 Webhook 類型而有所不同。每個機制都依賴金鑰。根據預設，會使用名為「default」的函式索引鍵。若要使用不同的金鑰，請設定 Webhook 提供者以下列其中一種方式傳送金鑰名稱與要求：

查詢字串：提供者會在查詢字串參數中 clientid 傳遞索引鍵名稱，例如 https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?clientid=<KEY_NAME>。
要求標頭：提供者會在標頭中 x-functions-clientid 傳遞密鑰名稱。

內容類型

將二進位和表單資料傳遞至非 C# 函式需要您使用適當的內容類型標頭。支援的內容類型包括 octet-stream 二進位數據和多部分類型。

已知問題

在非 C# 函式中，以內容類型 image/jpeg 傳送的要求會導致 string 傳遞至函式的值。在這種情況下，您可以手動將值轉換成 string 位元組陣列，以存取原始二進位數據。

限制

HTTP 要求長度的限制為 100 MB (104,857,600 個位元組)，而 URL 長度的限制為 4 KB (4,096 個位元組)。這些限制是由httpRuntime運行時間 Web.config 檔案的元素所指定。

如果使用 HTTP 觸發程式的函式未在 230 秒內完成， Azure Load Balancer 將會逾時並傳回 HTTP 502 錯誤。函式會繼續執行，但無法傳回 HTTP 回應。對於長時間執行的函式，我們建議您遵循異步模式，並傳回可偵測要求狀態的位置。如需函式執行時間長度的資訊，請參閱調整和裝載 - 取用方案。

下一步

從函式傳回 HTTP 回應

Azure Functions HTTP 觸發程序

範例

從查詢字串讀取參數

從 POST 要求讀取本文

從路由讀取參數

從 POST 要求讀取 POJO 本文

屬性

裝飾項目

註釋

組態

使用方式

承載

自訂 HTTP 端點

使用路由參數

HTTP 資料流（預覽）

使用用戶端身分識別

授權等級

函式存取金鑰

授權範圍 (函式層級)

主要金鑰 (管理員層級)

取得金鑰

API 金鑰授權

保護生產環境中 HTTP 端點的安全

啟用 App Service 驗證/授權

使用「Azure API 管理」(APIM) 來驗證要求

以隔離方式部署函式應用程式

Webhooks

WebHook 類型

GitHub Webhook \(英文\)

Slack Webhook

Webhook 和金鑰

內容類型

已知問題

限制

下一步

其他資源

Azure Functions HTTP 觸發程序

範例

從查詢字串讀取參數

從 POST 要求讀取本文

從路由讀取參數

從 POST 要求讀取 POJO 本文

屬性

裝飾項目

註釋

組態

使用方式

承載

自訂 HTTP 端點

使用路由參數

HTTP 資料流 （預覽）

使用用戶端身分識別

授權等級

函式存取金鑰

授權範圍 (函式層級)

主要金鑰 (管理員層級)

取得金鑰

API 金鑰授權

保護生產環境中 HTTP 端點的安全

啟用 App Service 驗證/授權

使用「Azure API 管理」(APIM) 來驗證要求

以隔離方式部署函式應用程式

Webhooks

WebHook 類型

GitHub Webhook \(英文\)

Slack Webhook

Webhook 和金鑰

內容類型

已知問題

限制

下一步

其他資源

HTTP 資料流（預覽）