Azure Functions HTTP 觸發程序

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

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

  • HTTP 204 No Content 具有 Functions 2.x 和更新版本中的空白主體
  • HTTP 200 OK 具有 Functions 1.x 中的空白主體

若要修改 HTTP 回應,請設定輸出繫結

如需有關 HTTP 繫結的詳細資訊,請參閱概觀輸出繫結參考

提示

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

範例

下列範例會顯示在查詢字串或 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");
}

屬性和註釋

C# 類別庫和 JAVA 中,可以使用 HttpTrigger 屬性來設定函式。

您可以設定授權層級和屬性建構參數、Webhook 類型和路由範本中可允許的 HTTP 方法。 如需有關這些設定的詳細資訊,請參閱設定

這個範例示範如何使用 HttpTrigger 屬性。

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

如需完整範例,請參閱觸發程序範例

組態

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

function.json 屬性 屬性內容 描述
type n/a 必要項目 - 必須設定為 httpTrigger
direction n/a 必要項目 - 必須設定為 in
name n/a 必要項目 - 函式程式碼中用於要求或要求主體的變數名稱。
authLevel AuthLevel 會判斷要求中必須存在哪些金鑰 (若有的話) 才能叫用函式。 授權層級可為下列其中一個值:
  • anonymous—不需要 API 金鑰。
  • function—需要函式專屬的 API 金鑰。 如果沒有提供任何值,此為預設值。
  • admin—需要主要金鑰。
如需詳細資訊,請參閱有關授權金鑰章節。
methods 方法 函式將回應的 HTTP 方法陣列。 如果未指定,函式將會回應所有的 HTTP 方法。 請參閱自訂 HTTP 端點
route 路由 會定義路由範本,從而控制函式所要回應的要求 URL。 如果沒有提供任何值,預設值為 <functionname>。 如需詳細資訊,請參閱自訂 HTTP 端點
webHookType WebHookType 只有針對 1.x 版執行階段才有支援。

會設定 HTTP 觸發程序作為指定提供者的 webhook 接收器。 如果設定這個屬性,請勿設定 methods 屬性。 Webhook 類型可以是下列值其中之一:
  • genericJson—一般用途的 Webhook 端點,不需要特定提供者的邏輯。 此設定會將要求限制為只有那些使用 HTTP POST 和包含 application/json 內容類型的要求。
  • github—函式會回應 GitHub Webhook。 請勿使用 authLevel 屬性搭配 GitHub Webhook。 如需詳細資訊,請參閱本文稍後的 GitHub Webhook 一節。
  • slack—函式會回應 Slack Webhook。 請勿使用 authLevel 屬性搭配 Slack Webhook。 如需詳細資訊,請參閱本文稍後的 Slack Webhook 一節。

Payload

觸發程序輸入類型會宣告為 HttpRequest 或自訂類型。 如果您選擇 HttpRequest,就會取得要求物件的完整存取權。 針對自訂的類型,執行階段會嘗試剖析 JSON 要求本文來設定物件屬性。

自訂 HTTP 端點

根據預設,當您為 HTTP 觸發程序建立函式時,將可透過下列形式的路由來定址該函式:

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

您可以在 HTTP 觸發程序的輸入繫結上使用選擇性的 route 屬性來自訂此路由。 舉例來說,下列 function.json 檔案定義了 HTTP 觸發程序的 route 屬性:

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

在使用此設定的情況下,現在便可使用下列路由來定址該函式,而不需使用原始路由。

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

這項設定可讓函式程式碼支援位址、 類別識別碼 中的兩個參數。如需如何在 URL 中標記路由參數的詳細資訊,請參閱 ASP.NET Core 中的路由

您可以將任何 Web API 路由條件約束與您的參數搭配使用。 下列 C# 函式程式碼會同時利用這兩個參數。

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

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

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

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

使用路由參數

定義函式 route 模式的路由參數可用於每個繫結。 例如,如果您有定義為 "route": "products/{id}" 的路由,則資料表儲存體繫結可以使用繫結設定中 {id} 參數的值。

下列設定顯示如何將 {id} 參數傳遞至繫結的 rowKey

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

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

您可以 invoke_URL_template 使用 清單函數Get 函數的 Azure Resource Manager api,以程式設計方式存取。

使用用戶端身分識別

如果您的函式應用程式使用 App Service 驗證/授權,您可以透過程式碼來檢視已驗證的用戶端相關資訊。 這項資訊是以由平台插入的要求標頭形式提供。

您也可以從繫結資料來讀取這項資訊。 這項功能僅適用於 Functions 2.x 和更新版本的執行階段。 它目前也僅適用於 .NET 語言。

已驗證用戶端的相關資訊可在 ClaimsPrincipal 中取得。 ClaimsPrincipal 可作為要求內容的一部分提供,如下列範例所示:

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

函式存取金鑰

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

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

當您更新函式金鑰值時,您必須手動將更新的金鑰值重新發佈至所有呼叫您函式的用戶端。

授權範圍 (函式層級)

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

  • Function:這些金鑰僅適用於據以定義它們的特定函式。 當做為 API 金鑰使用時,這些金鑰僅允許存取該函式。

  • 主機:具有主機範圍的金鑰可用來存取函數應用程式內的所有函式。 當做為 API 金鑰使用時,這些金鑰會允許存取函數應用程式中的任何函式。

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

主要金鑰 (管理員層級)

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

警告

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

取得金鑰

金鑰會當作您函數應用程式的一部分儲存於 Azure 中,並在加密後靜置。 若要查看您的金鑰、建立新的金鑰或將金鑰輪替至新的值,請流覽至 Azure 入口網站 中的其中一個 HTTP 觸發函式,然後選取 [函式 金鑰]。

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

您可以使用 Azure Resource Manager Api,以程式設計方式取得函數和主機金鑰。 有一些 Api 可 列出 函式索引鍵和 清單主機金鑰,而使用部署位置時,對等的 Api 是 清單功能金鑰 位置和 清單主機金鑰位置。

您也可以使用 Create 或 Update Function secret、create 或 update function secret位置、建立或更新 主機密碼 ,以及建立或 更新主機秘密 位置 api,以程式設計方式建立新的函式和主機金鑰。

您可以使用 刪除功能秘密刪除函數秘密位置、 刪除主機密碼,以及 刪除主機秘密 位置 api,以程式設計方式刪除函式和主機金鑰。

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

API 金鑰授權

大多數 HTTP 觸發程序範本都會要求在要求中有 API 金鑰。 因此,您的 HTTP 要求通常看起來會像以下 URL:

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

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

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

注意

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

在生產環境中保護 HTTP 端點

若要在生產環境中完全保護您的函式端點,您應該考慮實作下列其中一個函數應用程式等級安全性選項。 當使用這其中一種函數應用程式等級的安全性方法時,您應該將 HTTP 觸發的函式驗證等級設定為 anonymous

啟用 App Service 驗證/授權

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

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

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

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

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

Webhook

注意

Webhook 模式僅適用於 1.x 版 Functions 執行階段。 此變更已完成,可在版本 2.x 和更新版本中提升 HTTP 觸發程序的效能。

在版本 1.x 中,Webhook 範本會提供 Webhook 承載的額外驗證。 在 2.x 和更新版本中,基底 HTTP 觸發程序仍然可運作,並且對 Webhook 來說是建議採用的方法。

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 # 函式時,您需要使用適當的 content-type 標頭。 支援的內容類型包括 octet-stream 二進位資料和 多部分類型

已知問題

在非 C # 函式中,以 content-type 傳送的要求會 image/jpeg 產生傳給 string 函數的值。 在這類情況下,您可以手動將 string 值轉換為位元組陣列,以存取原始的二進位資料。

限制

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

如果使用 HTTP 觸發程序的函式未在約 230 秒內完成,Azure Load Balancer 將會逾時並傳回 HTTP 502 錯誤。 函式會繼續執行,但無法傳回 HTTP 回應。 對於長時間執行的函式,建議您遵循非同步模式,並傳回可以偵測要求狀態的位置。 如需函式可以執行多久的相關資訊,請參閱級別和裝載 - 使用情況方案

後續步驟