Azure Functions の HTTP トリガー

HTTP トリガーでは、HTTP 要求で関数を呼び出すことができます。 HTTP トリガーを使用して、サーバーなしの API を構築し、webhook に応答することができます。

HTTP によってトリガーされる関数の既定の戻り値は次のとおりです。

  • Functions 2.x 以降は、本文が空の HTTP 204 No Content
  • Functions 1.x は、本文が空の HTTP 200 OK

HTTP 応答を変更するには、出力バインドを構成します。

HTTP バインドの詳細については、概要出力バインドのリファレンスに関するページを参照してください。

ヒント

HTTP または webhook のバインディングを使用する予定がある場合は、不適切な HttpClient のインスタンス化によって生じるおそれのあるポートの枯渇を防止してください。 詳細については、「How to manage connections in Azure Functions」(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 該当なし 必須 - httpTrigger に設定する必要があります。
direction 該当なし 必須 - in に設定する必要があります。
name 該当なし 必須 - 要求または要求本文の関数コードで使用される変数名。
authLevel AuthLevel 関数を呼び出すために、要求にどのキーが存在する必要があるかを決定します。 承認レベルは、次のいずれかの値になります。
  • anonymous—API キーは必要ありません。
  • function—関数固有の API キーが必要です。 何も指定されなかった場合は、これが既定値になります。
  • admin—マスター キーが必要です。
詳しくは、承認キーに関するセクションをご覧ください。
methods メソッド 関数が応答する HTTP メソッドの配列。 指定しない場合、関数はすべての HTTP メソッドに応答します。 「HTTP エンドポイントのカスタマイズ」をご覧ください。
route Route 関数がどの要求 URL に応答するかを制御するルート テンプレートを定義します。 何も指定しなかった場合の既定値は <functionname> です。 詳しくは、「HTTP エンドポイントのカスタマイズ」をご覧ください。
webHookType WebHookType バージョン 1.x ランタイムでのみサポートされます。

指定したプロバイダーの webhook レシーバーとして機能する HTTP トリガーを構成します。 このプロパティを設定する場合は、methods プロパティを設定しないでください。 webhook の種類は、次のいずれかの値になります。
  • genericJson—特定のプロバイダー用のロジックを持たない汎用 webhook エンドポイントです。 この設定では、要求が、HTTP POST を使用していてコンテンツの種類が application/json であるものだけに制限されます。
  • github—関数は GitHub webhook に応答します。 GitHub webhook に対して authLevel プロパティを使用しないでください。 詳しくは、この記事で後述する「GitHub webhook」セクションをご覧ください。
  • slack—関数は Slack webhook に応答します。 Slack webhook に対して authLevel プロパティを使用しないでください。 詳しくは、この記事で後述する「Slack webhook」セクションをご覧ください。

ペイロード

トリガーの入力型は、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

この構成により、関数コードではアドレスに categoryid の 2 つのパラメーターをサポートできます。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 portal で HTTP によってトリガーされる関数のいずれかに移動し、 [関数の URL の取得] を選択します。

List 関数または Get 関数に対して Azure Resource Manager API を使用して、invoke_URL_template にプログラムでアクセスすることができます。

クライアント ID の操作

関数アプリが App Service の認証と承認を使用している場合は、コードから認証されたクライアントに関する情報を確認することができます。 この情報は、プラットフォームによって挿入された要求ヘッダーとして使用できます。

また、この情報はバインディング データから参照することもできます。 この機能は、Functions 2.x 以降の Functions ランタイムのみで使用可能です。 また、現在のところ .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;
}

関数のアクセス キー

関数を使用すると、開発中に HTTP 関数のエンドポイントにアクセスするのをより困難にするようにキーを使用できます。 HTTP によってトリガーされる関数で HTTP アクセス レベルが anonymous に設定されている場合を除き、要求には API アクセス キーが含まれている必要があります。

キーからは既定のセキュリティ メカニズムが与えられますが、運用環境で HTTP エンドポイントをセキュリティで保護する追加オプションの検討もお勧めします。 たとえば、パブリック アプリで共有シークレットを配布することは通常、良い習慣ではありません。 関数がパブリック クライアントから呼び出される場合、別のセキュリティ メカニズムの実装を検討することをお勧めします。 詳細については、運用環境で HTTP エンドポイントを保護するを参照してください。

関数キー値を更新したら、関数が呼び出されるすべてのクライアントに更新後のキー値を手動で再配布する必要があります。

承認スコープ (関数レベル)

関数レベルのキーには、2 つのアクセス スコープがあります。

  • 関数:これらのキーは、それらが定義されている特定の関数にのみ適用されます。 API キーとして使用した場合は、その関数だけがアクセスできます。

  • [Host](ホスト) : ホスト スコープのキーは、関数アプリ内のすべての関数にアクセスするために使用できます。 API キーとして使用した場合は、関数アプリ内のすべての関数がアクセスできます。

各キーには、参照用に名前が付けられており、関数レベルおよびホスト レベルで "default" という名前の既定のキーがあります。 関数キーが、ホスト キーよりも優先されます。 2 つのキーが同じ名前で定義されている場合は、関数キーが使用されます。

マスターキー (管理レベル)

各関数アプリには、_masterという管理レベルのホスト キーもあります。 マスター キーは、アプリ内のすべての関数へのホスト レベルのアクセスを提供するだけでなく、ランタイム REST API への管理アクセスも提供します。 このキーを取り消すことはできません。 アクセス レベルを admin に設定すると、要求でマスター キーを使用する必要があります。その他のキーを使用するとアクセス エラーになります。

注意事項

マスター キーによって付与された関数 app の権限が昇格しているため、このキーを第三者と共有したり、ネイティブ クライアント アプリケーションに配布したりしないでください。 管理者アクセス レベルを選択する場合は注意が必要です。

キーを入手する

キーは関数アプリの一部として Azure に格納され、保存中は暗号化されます。 キーを表示したり、新しいものを作成したり、新しい値にキーをロールしたりするには、Azure portal で HTTP によってトリガーされる関数のいずれかに移動して、 [関数キー] を選択します。

ホスト キーを管理することもできます。 Azure portal で関数アプリに移動し、[アプリ キー] を選択します。

関数およびホスト キーは、Azure Resource Manager API を使用してプログラムで取得できます。 List 関数キーList ホスト キーへの API があります。デプロイ スロットを使用する場合の同等の API は、List 関数キー スロット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というクエリ文字列変数に含めることができます。 x-functions-keyHTTP ヘッダーに含めることもできます。 キーの値には、関数のために定義されている任意の関数キーまたは任意のホスト キーを指定できます。

匿名要求を許可できます。この要求ではキーが不要です。 マスター キーを使用するように要求することもできます。 既定の承認レベルを変更するには、バインド JSON の authLevel プロパティを使用します。 詳しくは、「トリガー - 構成」をご覧ください。

注意

機能をローカルで実行する場合、指定された承認レベルの設定に関係なく、許可は無効になります。 Azure に発行した後、トリガーのauthLevel設定が適用されます。 コンテナーをローカルで実行する場合もキーが必要です。

運用環境で HTTP エンドポイントを保護します。

運用環境で、関数エンドポイントを完全に保護するには、次の関数アプリレベルのセキュリティ オプションのいずれかの実装を検討してください。 これらの関数アプリレベル セキュリティ メソッドのいずれかを使用する場合は、HTTP トリガー関数の承認レベルを anonymous に設定する必要があります。

App Service の認証/承認の有効化

App Service プラットフォームでは、Azure Active Directory (AAD) といくつかのサード パーティの ID プロバイダーを使用してクライアントを認証することができます。 この方法を使用して、関数のカスタム認可ルールを実装し、関数コードのユーザー情報を操作できます。 詳細については、「Azure App Service での認証および認可」および「クライアント ID の操作」を参照してください。

Azure API Management (APIM) を使用して要求を認証する

APIM では、受信要求用のさまざまな API のセキュリティ オプションを提供します。 詳細については、 API Management の認証ポリシーを参照してください。 APIM を適切に配置すると、APIM インスタンスの IP アドレスからの要求のみを受け入れるように関数アプリを設定できます。 詳細については、IP アドレス制限を参照してください。

関数アプリを分離してデプロイする

Azure App Service Environment (ASE) では、関数を実行するための専用のホスティング環境を提供します。 ASE では、すべての着信要求の認証に使用できる 1 つのフロント エンド ゲートウェイを構成できます。 詳細情報については、App Service 環境の Web アプリケーション ファイアウォール (WAF) を構成するを参照してください。

Webhooks

注意

Webhook モードは、関数ランタイムのバージョン 1.x でのみ使用できます。 この変更は、バージョン 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 の承認は、HTTP トリガーの一部である webhook レシーバー コンポーネントによって処理されますが、そのメカニズムは 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 応答を返すことはできません。 実行時間が長い関数の場合は、非同期パターンに従い、要求の状態について ping で確認できる場所を返すことをお勧めします。 関数を実行できる時間については、スケールとホスティングに関するページの「従量課金プラン」を参照してください。

次のステップ