共用方式為


Azure Functions HTTP 觸發程序

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.* 命名空間。

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

下列範例示範使用 .NET Isolated 中的 ASP.NET Core 整合,以 IActionResult 傳回「你好世界」回應的 HTTP 觸發程式:

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

下列範例顯示 HTTP 觸發程式,此觸發程式會以 HttpResponseData 物件的形式傳回 「你好 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 觸發程式系結。

從查詢字串讀取參數

此範例會從查詢字串讀取名為 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();
    }
}

下列範例顯示 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,
});

下列範例顯示 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檔案和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
})

此範例會使用 HTTP 資料流 傳回區塊響應數據。

import time

import azure.functions as func
from azurefunctions.extensions.http.fastapi import Request, StreamingResponse

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)


def generate_sensor_data():
    """Generate real-time sensor data."""
    for i in range(10):
        # Simulate temperature and humidity readings
        temperature = 20 + i
        humidity = 50 + i
        yield f"data: {{'temperature': {temperature}, 'humidity': {humidity}}}\n\n"
        time.sleep(1)


@app.route(route="stream", methods=[func.HttpMethod.GET])
async def stream_sensor_data(req: Request) -> StreamingResponse:
    """Endpoint to stream real-time sensor data."""
    return StreamingResponse(generate_sensor_data(), media_type="text/event-stream")

若要深入瞭解,包括如何在專案中啟用 HTTP 數據流,請參閱 HTTP 數據流

此範例顯示觸發程式系結,以及使用系結的 Python 函式。 函式會尋找 name 參數,其位於查詢字串或 HTTP 要求的主體。

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
        )

屬性

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

隔離的背景工作模型函 式應用程式中, HttpTriggerAttribute 支援下列參數:

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

裝飾項目

僅適用於 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 函式,請參閱組 一節。

組態

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

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

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

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

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

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

使用方式

本節詳細說明如何設定 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 路由條件約束 搭配您的參數。

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

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

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

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

例如,下列 TypeScript 程式代碼會使用兩個 route 參數 category id和 來定義 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,
});

例如,下列 JavaScript 程式代碼會使用兩個 route 參數 category id和 來定義 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}` };
    },
});

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

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

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

當您使用路由參數時, 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 數據流

HTTP 數據流

Python 中的 HTTP 串流支援可讓您使用在函式中啟用的 FastAPI 要求和回應 API,從 HTTP 端點接受和傳回數據。 這些 API 可讓主機以區塊的形式處理 HTTP 訊息中的數據,而不必將整個訊息讀入記憶體。 如需詳細資訊,請參閱 Python 中的 HTTP 數據流

重要

Python 的 HTTP 數據流支援目前為預覽狀態,且僅支援 Python v2 程式設計模型。

使用用戶端身分識別

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

您也可以從系結數據讀取這項資訊。

注意

存取已驗證的用戶端資訊目前僅適用於 .NET 語言。 Functions 運行時間 1.x 版也不支援。

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

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

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

授權等級

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

層級值 描述
anonymous 不需要存取金鑰。
函數 需要函式特定金鑰才能存取端點。
admin 需要主要金鑰才能存取端點。

如果未明確設定層級,授權預設為 function 層級。

如果未明確設定層級,默認授權取決於Node.js模型的版本:

授權預設為 anonymous 層級。

函式存取金鑰

Functions 可讓您使用存取金鑰,讓您更難存取函式端點。 除非 HTTP 觸發函式上的授權層級設定為 anonymous,否則要求必須在要求中包含存取密鑰。 如需詳細資訊,請參閱 在 Azure Functions 中使用存取密鑰。

存取金鑰授權

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

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

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

您可以允許不需要金鑰的匿名要求。 您也可以要求使用主要金鑰。 您可以使用系結 JSON 中的 屬性來變更預設授權層級 authLevel

注意

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

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 回應。 對於長時間執行的函式,我們建議您遵循異步模式,並傳回可偵測要求狀態的位置。 如需函式執行時間長度的資訊,請參閱 調整和裝載 - 取用方案

下一步