Azure Functions のトリガーとバインドAzure Functions HTTP triggers and bindings

この記事では、Azure Functions で HTTP トリガーと出力バインドを操作する方法について説明します。This article explains how to work with HTTP triggers and output bindings in Azure Functions.

HTTP トリガーは webhook に応答するようにカスタマイズすることができます。An HTTP trigger can be customized to respond to webhooks.

これは、Azure Functions の開発者向けリファレンス情報です。This is reference information for Azure Functions developers. Azure Functions を初めて使用する場合は、先に次のリソースを参照してください。If you're new to Azure Functions, start with the following resources:

ヒント

HTTP または webhook のバインディングを使用する予定がある場合は、不適切な HttpClient のインスタンス化によって生じるおそれのあるポートの枯渇を防止してください。If you plan to use the HTTP or WebHook bindings, plan to avoid port exhaustion that can be caused by improper instantiation of HttpClient. 詳細については、「How to manage connections in Azure Functions」(Azure Functions で接続を管理する方法) を参照してください。For more information, see How to manage connections in Azure Functions.

この記事のコードは .NET Core を使用する Functions 2.x 構文が既定です。The code in this article defaults to Functions 2.x syntax which uses .NET Core. 1.x 構文については、1.x 関数テンプレートを参照してください。For information on the 1.x syntax, see the 1.x functions templates.

パッケージ - Functions 1.xPackages - Functions 1.x

HTTP バインディングは Microsoft.Azure.WebJobs.Extensions.Http NuGet パッケージ バージョン 1.x で提供されます。The HTTP bindings are provided in the Microsoft.Azure.WebJobs.Extensions.Http NuGet package, version 1.x. パッケージのソース コードは、azure-webjobs-sdk-extensions GitHub リポジトリにあります。Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

このバインドのサポートは、すべての開発環境で自動的に提供されます。Support for this binding is automatically provided in all development environments. 手動でパッケージをインストールしたり、拡張機能を登録したりする必要はありません。You don't have to manually install the package or register the extension.

パッケージ - Functions 2.xPackages - Functions 2.x

HTTP バインディングは Microsoft.Azure.WebJobs.Extensions.Http NuGet パッケージ バージョン 3.x で提供されます。The HTTP bindings are provided in the Microsoft.Azure.WebJobs.Extensions.Http NuGet package, version 3.x. パッケージのソース コードは、azure-webjobs-sdk-extensions GitHub リポジトリにあります。Source code for the package is in the azure-webjobs-sdk-extensions GitHub repository.

このバインドのサポートは、すべての開発環境で自動的に提供されます。Support for this binding is automatically provided in all development environments. 手動でパッケージをインストールしたり、拡張機能を登録したりする必要はありません。You don't have to manually install the package or register the extension.

トリガーTrigger

HTTP トリガーでは、HTTP 要求で関数を呼び出すことができます。The HTTP trigger lets you invoke a function with an HTTP request. HTTP トリガーを使用して、サーバーなしの API を構築し、webhook に応答することができます。You can use an HTTP trigger to build serverless APIs and respond to webhooks.

既定では、HTTP トリガーは、Functions 1.x では HTTP 200 OK と空の本文を返し、Functions 2.x では HTTP 204 No Content と空の本文を返します。By default, an HTTP trigger returns HTTP 200 OK with an empty body in Functions 1.x, or HTTP 204 No Content with an empty body in Functions 2.x. 応答を変更するには、HTTP 出力バインドを構成します。To modify the response, configure an HTTP output binding.

トリガー - 例Trigger - example

言語固有の例をご覧ください。See the language-specific example:

トリガー - C# の例Trigger - C# example

次の例は、クエリ文字列または HTTP 要求の本文で nameパラメーターを探す C# 関数を示しています。The following example shows a C# function that looks for a name parameter either in the query string or the body of the HTTP request. 戻り値は出力バインドの使われますが、戻り値の属性は必要ないことに注意してください。Notice that the return value is used for the output binding, but a return value attribute isn't required.

[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 = await new StreamReader(req.Body).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# スクリプトの例Trigger - C# script example

次の例は、function.json ファイルのトリガー バインドと、そのバインドが使用される C# スクリプト関数を示しています。The following example shows a trigger binding in a function.json file and a C# script function that uses the binding. この関数は、クエリ文字列または HTTP 要求の本文で name パラメーターを探します。The function looks for a name parameter either in the query string or the body of the HTTP request.

function.json ファイルを次に示します。Here's the function.json file:

{
    "disabled": false,
    "bindings": [
        {
            "authLevel": "function",
            "name": "req",
            "type": "httpTrigger",
            "direction": "in",
            "methods": [
                "get",
                "post"
            ]
        },
        {
            "name": "$return",
            "type": "http",
            "direction": "out"
        }
    ]
}

これらのプロパティについては、「構成」セクションを参照してください。The configuration section explains these properties.

HttpRequest にバインドする C# スクリプト コードを次に示します。Here's C# script code that binds to HttpRequest:

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

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    string name = req.Query["name"];

    string requestBody = await new StreamReader(req.Body).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");
}

HttpRequest の代わりにカスタム オブジェクトにバインドできます。You can bind to a custom object instead of HttpRequest. このオブジェクトは要求の本文から作成され、JSON として解析されます。This object is created from the body of the request and parsed as JSON. 同様に、型は HTTP 応答出力バインディングに渡すことができ、200 のステータス コードと共に、応答本文として返されます。Similarly, a type can be passed to the HTTP response output binding and returned as the response body, along with a 200 status code.

using System.Net;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

public static string Run(Person person, ILogger log)
{   
    return person.Name != null
        ? (ActionResult)new OkObjectResult($"Hello, {person.Name}")
        : new BadRequestObjectResult("Please pass an instance of Person.");
}

public class Person {
     public string Name {get; set;}
}

トリガー - F# の例Trigger - F# example

次の例は、function.json ファイルのトリガー バインドと、そのバインドが使用される F# 関数を示しています。The following example shows a trigger binding in a function.json file and an F# function that uses the binding. この関数は、クエリ文字列または HTTP 要求の本文で name パラメーターを探します。The function looks for a name parameter either in the query string or the body of the HTTP request.

function.json ファイルを次に示します。Here's the function.json file:

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

これらのプロパティについては、「構成」セクションを参照してください。The configuration section explains these properties.

F# コードを次に示します。Here's the F# code:

open System.Net
open System.Net.Http
open FSharp.Interop.Dynamic

let Run(req: HttpRequestMessage) =
    async {
        let q =
            req.GetQueryNameValuePairs()
                |> Seq.tryFind (fun kv -> kv.Key = "name")
        match q with
        | Some kv ->
            return req.CreateResponse(HttpStatusCode.OK, "Hello " + kv.Value)
        | None ->
            let! data = Async.AwaitTask(req.Content.ReadAsAsync<obj>())
            try
                return req.CreateResponse(HttpStatusCode.OK, "Hello " + data?name)
            with e ->
                return req.CreateErrorResponse(HttpStatusCode.BadRequest, "Please pass a name on the query string or in the request body")
    } |> Async.StartAsTask

次の例に示すように、NuGet を使用して FSharp.Interop.Dynamic および Dynamitey アセンブリを参照する project.json ファイルが必要です。You need a project.json file that uses NuGet to reference the FSharp.Interop.Dynamic and Dynamitey assemblies, as shown in the following example:

{
  "frameworks": {
    "net46": {
      "dependencies": {
        "Dynamitey": "1.0.2",
        "FSharp.Interop.Dynamic": "3.0.0"
      }
    }
  }
}

トリガー - JavaScript の例Trigger - JavaScript example

次の例は、function.json ファイルのトリガー バインドと、そのバインドを使用する JavaScript 関数を示しています。The following example shows a trigger binding in a function.json file and a JavaScript function that uses the binding. この関数は、クエリ文字列または HTTP 要求の本文で name パラメーターを探します。The function looks for a name parameter either in the query string or the body of the HTTP request.

function.json ファイルを次に示します。Here's the function.json file:

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

これらのプロパティについては、「構成」セクションを参照してください。The configuration section explains these properties.

JavaScript コードを次に示します。Here's the JavaScript code:

module.exports = 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"
        };
    }
    context.done();
};

トリガー - Python の例Trigger - Python example

次の例は、function.json ファイルのトリガー バインドと、そのバインドが使用される Python 関数を示しています。The following example shows a trigger binding in a function.json file and a Python function that uses the binding. この関数は、クエリ文字列または HTTP 要求の本文で name パラメーターを探します。The function looks for a name parameter either in the query string or the body of the HTTP request.

function.json ファイルを次に示します。Here's the function.json file:

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

これらのプロパティについては、「構成」セクションを参照してください。The configuration section explains these properties.

Python コードを次に示します。Here's the Python code:

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
        )

トリガー - Java の例Trigger - Java examples

次の例は、function.json ファイルの HTTP トリガー バインドと、そのバインドを使用する個別の Java 関数を示しています。The following examples show the HTTP trigger binding in a function.json file and the respective Java functions that use the binding.

function.json ファイルを次に示します。Here's the function.json file:

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

クエリ文字列からのパラメーターの読み取り (Java)Read parameter from the query string (Java)

この例では、クエリ文字列から id という名前のパラメーターを読み取り、そのパラメーターを使用して、コンテンツ タイプ application/json でクライアントに返される JSON ドキュメントを作成します。This example reads a parameter, named id, from the query string, and uses it to build a JSON document returned to the client, with content type 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 要求からの本文の読み取り (Java)Read body from a POST request (Java)

この例では、Post 要求の本文を String として読み取り、その内容を使用して、コンテンツ タイプ application/json でクライアントに返される JSON ドキュメントを作成します。This example reads the body of a POST request, as a String, and uses it to build a JSON document returned to the client, with content type 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();
        }
    }

ルートからのパラメーターの読み取り (Java)Read parameter from a route (Java)

この例では、ルート パスから id という名前の必須パラメーターとオプション パラメーター name を読み取り、それらのパラメーターを使用して、コンテンツ タイプ application/json でクライアントに返される JSON ドキュメントを作成します。This example reads a mandatory parameter, named id, and an optional parameter name from the route path, and uses them to build a JSON document returned to the client, with content type application/json. TT

    @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 本文の読み取り (Java)Read POJO body from a POST request (Java)

この例で参照されるクラス ToDoItem のコードを次に示します。Here is the code for the ToDoItem class, referenced in this example:


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 要求の本文を読み取ります。This example reads the body of a POST request. 要求本文を ToDoItem オブジェクトに自動的に逆シリアル化し、コンテンツ タイプ application/json でクライアントに返します。The request body gets automatically de-serialized into a ToDoItem object, and is returned to the client, with content type application/json. ToDoItem パラメーターは、HttpMessageResponse.Builder クラスの body プロパティに割り当てられる際に、Functions ランタイムによってシリアル化されます。The ToDoItem parameter is serialized by the Functions runtime as it is assigned to the body property of the HttpMessageResponse.Builder class.

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

トリガー - 属性Trigger - attributes

C# クラス ライブラリでは、HttpTrigger 属性を使用します。In C# class libraries, use the HttpTrigger attribute.

属性のコンストラクターのパラメーターに承認レベルと許容される HTTP メソッドを設定できます。また、webhook の種類とルートのテンプレートに対応するプロパティがあります。You can set the authorization level and allowable HTTP methods in attribute constructor parameters, and there are properties for webhook type and route template. これらの設定の詳細については、「トリガー - 構成」を参照してください。For more information about these settings, see Trigger - configuration. メソッド シグネチャでの HttpTrigger 属性を次に示します。Here's an HttpTrigger attribute in a method signature:

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

完全な例については、「トリガー - C# の例」を参照してください。For a complete example, see Trigger - C# example.

トリガー - 構成Trigger - configuration

次の表は、function.json ファイルと HttpTrigger 属性で設定したバインド構成のプロパティを説明しています。The following table explains the binding configuration properties that you set in the function.json file and the HttpTrigger attribute.

function.json のプロパティfunction.json property 属性のプロパティAttribute property 説明Description
typetype 該当なしn/a 必須 - httpTrigger に設定する必要があります。Required - must be set to httpTrigger.
directiondirection 該当なしn/a 必須 - in に設定する必要があります。Required - must be set to in.
namename 該当なしn/a 必須 - 要求または要求本文の関数コードで使用される変数名。Required - the variable name used in function code for the request or request body.
authLevelauthLevel AuthLevelAuthLevel 関数を呼び出すために、要求にどのキーが存在する必要があるかを決定します。Determines what keys, if any, need to be present on the request in order to invoke the function. 承認レベルは、次のいずれかの値になります。The authorization level can be one of the following values:
  • anonymous—API キーは必要ありません。anonymous—No API key is required.
  • function—関数固有の API キーが必要です。function—A function-specific API key is required. 何も指定されなかった場合は、これが既定値になります。This is the default value if none is provided.
  • admin—マスター キーが必要です。admin—The master key is required.
詳しくは、承認キーに関するセクションをご覧ください。For more information, see the section about authorization keys.
methodsmethods メソッドMethods 関数が応答する HTTP メソッドの配列。An array of the HTTP methods to which the function responds. 指定しない場合、関数はすべての HTTP メソッドに応答します。If not specified, the function responds to all HTTP methods. HTTP エンドポイントのカスタマイズ」をご覧ください。See customize the http endpoint.
routeroute RouteRoute 関数がどの要求 URL に応答するかを制御するルート テンプレートを定義します。Defines the route template, controlling to which request URLs your function responds. 何も指定しなかった場合の既定値は <functionname> です。The default value if none is provided is <functionname>. 詳しくは、「HTTP エンドポイントのカスタマイズ」をご覧ください。For more information, see customize the http endpoint.
webHookTypewebHookType WebHookTypeWebHookType バージョン 1.x ランタイムでのみサポートされます。Supported only for the version 1.x runtime.

指定したプロバイダーの webhook レシーバーとして機能する HTTP トリガーを構成します。Configures the HTTP trigger to act as a webhook receiver for the specified provider. このプロパティを設定する場合は、methods プロパティを設定しないでください。Don't set the methods property if you set this property. webhook の種類は、次のいずれかの値になります。The webhook type can be one of the following values:
  • genericJson—特定のプロバイダー用のロジックを持たない汎用 webhook エンドポイントです。genericJson—A general-purpose webhook endpoint without logic for a specific provider. この設定では、要求が、HTTP POST を使用していてコンテンツの種類が application/json であるものだけに制限されます。This setting restricts requests to only those using HTTP POST and with the application/json content type.
  • github—関数は GitHub webhook に応答します。github—The function responds to GitHub webhooks. GitHub webhook に対して authLevel プロパティを使用しないでください。Do not use the authLevel property with GitHub webhooks. 詳しくは、この記事で後述する「GitHub webhook」セクションをご覧ください。For more information, see the GitHub webhooks section later in this article.
  • slack—関数は Slack webhook に応答します。slack—The function responds to Slack webhooks. Slack webhook に対して authLevel プロパティを使用しないでください。Do not use the authLevel property with Slack webhooks. 詳しくは、この記事で後述する「Slack webhook」セクションをご覧ください。For more information, see the Slack webhooks section later in this article.

トリガー - 使用方法Trigger - usage

C# および F# の関数では、トリガー入力の型を HttpRequest 型かカスタム型として宣言できます。For C# and F# functions, you can declare the type of your trigger input to be either HttpRequest or a custom type. HttpRequest を選択した場合は、要求オブジェクトへのフル アクセスが取得されます。If you choose HttpRequest, you get full access to the request object. カスタム型 の場合、ランタイムは JSON 要求本文を解析して、オブジェクトのプロパティを設定しようとします。For a custom type, the runtime tries to parse the JSON request body to set the object properties.

JavaScript 関数の場合、Functions ランタイムは request オブジェクトではなく、要求本文を提供します。For JavaScript functions, the Functions runtime provides the request body instead of the request object. 詳しくは、JavaScript トリガーの例をご覧ください。For more information, see the JavaScript trigger example.

HTTP エンドポイントのカスタマイズCustomize the HTTP endpoint

既定では、HTTP トリガーの関数を作成する際に、次の形式のルートを使用して関数のアドレスを指定できます。By default when you create a function for an HTTP trigger, the function is addressable with a route of the form:

http://<yourapp>.azurewebsites.net/api/<funcname>

HTTP トリガーの入力バインドで省略可能な route プロパティを使用すると、このルートをカスタマイズできます。You can customize this route using the optional route property on the HTTP trigger's input binding. たとえば、次の function.json ファイルでは HTTP トリガーの route プロパティを定義します。As an example, the following function.json file defines a route property for an HTTP trigger:

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

この構成を使用すると、元のルートではなく、次のルートを使用して関数のアドレスを指定できるようになります。Using this configuration, the function is now addressable with the following route instead of the original route.

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

これにより、関数のコードはアドレス内で categoryid という 2 つのパラメーターをサポートできます。パラメーターでは任意の Web API ルート制約を使用できます。This allows the function code to support two parameters in the address, category and id. You can use any Web API Route Constraint with your parameters. 次の C# 関数コードは両方のパラメーターを使用します。The following C# function code makes use of both parameters.

public static Task<IActionResult> Run(HttpRequest req, string category, int? id, ILogger log)
{
    if (id == null)
    {
        return (ActionResult)new OkObjectResult($"All {category} items were requested.");
    }
    else
    {
        return (ActionResult)new OkObjectResult($"{category} item with id = {id} has been requested.");
    }
    
    // -----
    log.LogInformation($"C# HTTP trigger function processed a request. RequestUri={req.RequestUri}");
}

同じルート パラメーターを使用する Node.js 関数コードを次に示します。Here is Node.js function code that uses the same route parameters.

module.exports = function (context, req) {

    var category = context.bindingData.category;
    var id = context.bindingData.id;

    if (!id) {
        context.res = {
            // status defaults to 200 */
            body: "All " + category + " items were requested."
        };
    }
    else {
        context.res = {
            // status defaults to 200 */
            body: category + " item with id = " + id + " was requested."
        };
    }

    context.done();
}

既定では、すべての関数のルートには api というプレフィックスが付きます。By default, all function routes are prefixed with api. host.json ファイルで http.routePrefix プロパティを使用すると、このプレフィックスをカスタマイズまたは削除できます。You can also customize or remove the prefix using the http.routePrefix property in your host.json file. 次の例では、host.json ファイル内でプレフィックスに空の文字列を使用することで、api ルート プレフィックスを削除します。The following example removes the api route prefix by using an empty string for the prefix in the host.json file.

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

クライアント ID の操作Working with client identities

関数アプリが App Service の認証と承認を使用している場合は、コードから認証されたクライアントに関する情報を確認することができます。If your function app is using App Service Authentication / Authorization, you can view information about authenticated clients from your code. この情報は、プラットフォームによって挿入された要求ヘッダーとして使用できます。This information is available as request headers injected by the platform.

また、この情報はバインディング データから参照することもできます。You can also read this information from binding data. この機能は、Functions 2.x ランタイムのみで使用可能です。This capability is only available to the Functions 2.x runtime. また、現在のところ .NET 言語でのみ使用可能です。It is also currently only available for .NET languages.

.NET 言語では、この情報は ClaimsPrincipal として使用可能です。In .NET languages, this information is available as a ClaimsPrincipal. ClaimsPrincipal は、次の例に示すように、要求コンテキストの一部として使用可能です。The ClaimsPrincipal is available as part of the request context as shown in the following example:

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 を単に追加のパラメーターとして関数シグネチャに含めることもできます。Alternatively, the ClaimsPrincipal can simply be included as an additional parameter in the function signature:

#r "Newtonsoft.Json"

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

承認キーAuthorization keys

関数を使用すると、開発中に HTTP 関数のエンドポイントにアクセスするのをより困難にするようにキーを使用できます。Functions lets you use keys to make it harder to access your HTTP function endpoints during development. 標準の HTTP トリガーでは、そのような API キーが要求内に存在する必要があります。A standard HTTP trigger may require such an API key be present in the request.

重要

キーは開発中に HTTP エンドポイントを難読化するのに役立つかもしれませんが、運用環境で HTTP トリガーを確保する方法としては意図されていません。While keys may help obfuscate your HTTP endpoints during development, they are not intended as a way to secure an HTTP trigger in production. 詳細については、運用環境で HTTP エンドポイントを保護するを参照してください。To learn more, see Secure an HTTP endpoint in production.

注意

Functions 1.x ランタイムでは、Webhook プロバイダーは、プロバイダーがサポートするものに応じて、さまざまな方法で要求を認可するためにキーを使用することがあります。In the Functions 1.x runtime, webhook providers may use keys to authorize requests in a variety of ways, depending on what the provider supports. これについては、Webhook とキーを参照してください。This is covered in Webhooks and keys. バージョン 2.x ランタイムには、Webhook プロバイダーの組み込みサポートは含まれていません。The version 2.x runtime does not include built-in support for webhook providers.

キーには、次の 2 つの種類があります。There are two types of keys:

  • ホスト キー:これらのキーは、関数アプリ内のすべての関数で共有されます。Host keys: These keys are shared by all functions within the function app. API キーとして使用した場合は、関数アプリ内のすべての関数がアクセスできます。When used as an API key, these allow access to any function within the function app.
  • 関数キー:これらのキーは、それらが定義されている特定の関数にのみ適用されます。Function keys: These keys apply only to the specific functions under which they are defined. API キーとして使用した場合は、その関数だけがアクセスできます。When used as an API key, these only allow access to that function.

各キーには、参照用に名前が付けられており、関数レベルおよびホスト レベルで "default" という名前の既定のキーがあります。Each key is named for reference, and there is a default key (named "default") at the function and host level. 関数キーが、ホスト キーよりも優先されます。Function keys take precedence over host keys. 2 つのキーが同じ名前で定義されている場合は、関数キーが使用されます。When two keys are defined with the same name, the function key is always used.

各関数アプリには特別なマスター キーもあります。Each function app also has a special master key. このキーは_masterという名前のホスト キーで、ランタイム API への管理アクセスを提供します。This key is a host key named _master, which provides administrative access to the runtime APIs. このキーを取り消すことはできません。This key cannot be revoked. 認可レベルをadminに設定すると、要求でマスター キーを使用する必要があります。 その他のキーを使用すると認可エラーになります。When you set an authorization level of admin, requests must use the master key; any other key results in authorization failure.

注意事項

マスター キーによって付与された関数 app の権限が昇格しているため、このキーを第三者と共有したり、ネイティブ クライアント アプリケーションに配布したりしないでください。Due to the elevated permissions in your function app granted by the master key, you should not share this key with third parties or distribute it in native client applications. 管理者承認レベルを選択する場合は注意が必要です。Use caution when choosing the admin authorization level.

キーを入手するObtaining keys

キーは関数アプリの一部として Azure に格納され、保存中は暗号化されます。Keys are stored as part of your function app in Azure and are encrypted at rest. キーを表示には、新しい値を作成したり、新しい値にキーをロールしたり、Azure ポータルで HTTP トリガー機能に移動して、管理を選択します。To view your keys, create new ones, or roll keys to new values, navigate to one of your HTTP-triggered functions in the Azure portal and select Manage.

ポータルでのファンクション キーを管理します。

ファンクション キーをプログラムで取得するためのサポートされている API はありません。There is no supported API for programmatically obtaining function keys.

API キーの承認API key authorization

ほとんどの HTTP トリガー テンプレートには、要求内の API キーが必要です。Most HTTP trigger templates require an API key in the request. そのため、HTTP 要求は、通常は次の URL のようになります。So your HTTP request normally looks like the following URL:

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

上記のように、キーはcodeというクエリ文字列変数に含めることができます。The key can be included in a query string variable named code, as above. x-functions-keyHTTP ヘッダーに含めることもできます。It can also be included in an x-functions-key HTTP header. キーの値には、関数のために定義されている任意の関数キーまたは任意のホスト キーを指定できます。The value of the key can be any function key defined for the function, or any host key.

匿名要求を許可できます。この要求ではキーが不要です。You can allow anonymous requests, which do not require keys. マスター キーを使用するように要求することもできます。You can also require that the master key be used. 既定の承認レベルを変更するには、バインド JSON の authLevel プロパティを使用します。You change the default authorization level by using the authLevel property in the binding JSON. 詳しくは、「トリガー - 構成」をご覧ください。For more information, see Trigger - configuration.

注意

機能をローカルで実行する場合、指定された認証レベルの設定に関係なく、許可は無効になります。When running functions locally, authorization is disabled regardless of the specified authentication level setting. Azure に発行した後、トリガーのauthLevel設定が適用されます。After publishing to Azure, the authLevel setting in your trigger is enforced.

運用環境で HTTP エンドポイントを保護します。Secure an HTTP endpoint in production

運用環境で、関数エンドポイントを完全に保護するには、次の関数アプリ レベルのセキュリティ オプションのいずれかの実装を検討してください。To fully secure your function endpoints in production, you should consider implementing one of the following function app-level security options:

  • 機能アプリの App サービス認証/認可をオンにします。Turn on App Service Authentication / Authorization for your function app. App Service プラットフォームでは、Azure Active Directory (AAD) といくつかのサード パーティの ID プロバイダーを使用してクライアントを認証することができます。The App Service platform lets use Azure Active Directory (AAD) and several third-party identity providers to authenticate clients. これを使用して、関数のカスタム認可ルールを実装し、関数コードのユーザー情報を操作できます。You can use this to implement custom authorization rules for your functions, and you can work with user information from your function code. 詳細については、「Azure App Service での認証および認可」および「クライアント ID の操作」を参照してください。To learn more, see Authentication and authorization in Azure App Service and Working with client identities.

  • 要求の認証に Azure API Management (APIM) を使用します。Use Azure API Management (APIM) to authenticate requests. APIM では、受信要求用のさまざまな API のセキュリティ オプションを提供します。APIM provides a variety of API security options for incoming requests. 詳細については、 API Management の認証ポリシーを参照してください。To learn more, see API Management authentication policies. APIM を適切に配置すると、APIM インスタンスの IP アドレスからの要求のみを受け入れるように関数アプリを設定できます。With APIM in place, you can configure your function app to accept requests only from the IP address of your APIM instance. 詳細については、IP アドレス制限を参照してください。To learn more, see IP address restrictions.

  • Azure App Service 環境 (ASE) で関数アプリをデプロイします。Deploy your function app to an Azure App Service Environment (ASE). ASE では、関数を実行するための専用のホスティング環境を提供します。ASE provides a dedicated hosting environment in which to run your functions. ASE では、すべての着信要求の認証に使用できる 1 つのフロント エンド ゲートウェイを構成できます。ASE lets you configure a single front-end gateway that you can use to authenticate all incoming requests. 詳細情報については、App Service 環境の Web アプリケーション ファイアウォール (WAF) を構成するを参照してください。For more information, see Configuring a Web Application Firewall (WAF) for App Service Environment.

これらの関数アプリレベル セキュリティ メソッドのいずれかを使用する場合は、HTTP トリガー関数認証レベルをanonymousに設定する必要があります。When using one of these function app-level security methods, you should set the HTTP-triggered function authentication level to anonymous.

WebhookWebhooks

注意

Webhook モードは、関数ランタイムのバージョン 1.x でのみ使用できます。Webhook mode is only available for version 1.x of the Functions runtime. この変更は、バージョン 2.x での HTTP トリガーのパフォーマンスを向上させるために行われました。This change was made to improve the performance of HTTP triggers in version 2.x.

バージョン 1.x では、Webhook テンプレートで Webhook ペイロードの追加検証が提供されます。In version 1.x, webhook templates provide additional validation for webhook payloads. バージョン 2.x では、基本 HTTP トリガーは引き続き機能し、Webhook の推奨アプローチです。In version 2.x, the base HTTP trigger still works and is the recommended approach for webhooks.

GitHub webhookGitHub webhooks

GitHub webhook に応答するには、まず、HTTP トリガーで関数を作成し、webHookType プロパティを github に設定します。To respond to GitHub webhooks, first create your function with an HTTP Trigger, and set the webHookType property to github. 次に、その URL と API キーを GitHub リポジトリの [webhook の追加] ページにコピーします。Then copy its URL and API key into the Add webhook page of your GitHub repository.

Slack webhookSlack webhooks

Slack webhook では、指定しなくてもトークンが自動的に生成されます。そのため、Slack によって生成されたトークンで、関数固有のキーを構成する必要があります。The Slack webhook generates a token for you instead of letting you specify it, so you must configure a function-specific key with the token from Slack. 承認キー」をご覧ください。See Authorization keys.

Webhook とキーWebhooks and keys

webhook の承認は、HTTP トリガーの一部である webhook レシーバー コンポーネントによって処理されますが、そのメカニズムは webhook の種類によって異なります。Webhook authorization is handled by the webhook receiver component, part of the HTTP trigger, and the mechanism varies based on the webhook type. ただし、各メカニズムはキーに依存します。Each mechanism does rely on a key. 既定では、"default" という名前の関数キーが使用されます。By default, the function key named "default" is used. 別のキーを使用するには、次のいずれかの方法で、要求と共にキー名を送信するように webhook プロバイダーを構成します。To use a different key, configure the webhook provider to send the key name with the request in one of the following ways:

  • クエリ文字列:プロバイダーにより、clientid クエリ文字列パラメーターでキー名 (https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?clientid=<KEY_NAME> など) が渡されます。Query string: The provider passes the key name in the clientid query string parameter, such as https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?clientid=<KEY_NAME>.
  • 要求ヘッダー:プロバイダーにより、x-functions-clientid ヘッダーでキー名が渡されます。Request header: The provider passes the key name in the x-functions-clientid header.

トリガー - 制限Trigger - limits

HTTP 要求の長さは 100 MB (104,857,600 バイト) に、URL の長さは 4 KB (4,096 バイト) バイトに制限されています。The HTTP request length is limited to 100 MB (104,857,600 bytes), and the URL length is limited to 4 KB (4,096 bytes). これらの制限は、ランタイムの Web.config ファイルhttpRuntime 要素で指定されています。These limits are specified by the httpRuntime element of the runtime's Web.config file.

HTTP トリガーを使用する関数が約 2.5 分以内に完了しない場合、ゲートウェイでタイムアウトが発生し、HTTP 502 エラーが返されます。If a function that uses the HTTP trigger doesn't complete within about 2.5 minutes, the gateway will time out and return an HTTP 502 error. この関数は実行を継続しますが、HTTP 応答を返すことはできません。The function will continue running but will be unable to return an HTTP response. 実行時間が長い関数の場合は、非同期パターンに従い、要求の状態について ping で確認できる場所を返すことをお勧めします。For long-running functions, we recommend that you follow async patterns and return a location where you can ping the status of the request. 関数を実行できる時間については、スケールとホスティングに関するページの「従量課金プラン」を参照してください。For information about how long a function can run, see Scale and hosting - Consumption plan.

トリガー - host.json のプロパティTrigger - host.json properties

host.json ファイルには、HTTP トリガーの動作を制御する設定が含まれています。The host.json file contains settings that control HTTP trigger behavior.

{
    "http": {
        "routePrefix": "api",
        "maxOutstandingRequests": 200,
        "maxConcurrentRequests": 100,
        "dynamicThrottlesEnabled": true
    }
}
プロパティProperty 既定値Default 説明Description
routePrefixroutePrefix apiapi すべてのルートに適用されるルート プレフィックス。The route prefix that applies to all routes. 既定のプレフィックスを削除するには、空の文字列を使用します。Use an empty string to remove the default prefix.
maxOutstandingRequestsmaxOutstandingRequests 200*200* 特定の時点で保持される未処理の要求の最大数。The maximum number of outstanding requests that are held at any given time. この制限には、キューに格納され、まだ実行が開始されていない要求と、処理中の実行が含まれます。This limit includes requests that are queued but have not started executing, as well as any in progress executions. この制限を超える受信要求は、429 "Too Busy" 応答で拒否されます。Any incoming requests over this limit are rejected with a 429 "Too Busy" response. これにより、呼び出し元は時間ベースの再試行戦略を採用でき、要求の最大待機時間の制御にも役立ちます。That allows callers to employ time-based retry strategies, and also helps you to control maximum request latencies. この設定は、スクリプト ホストの実行パス内で発生するキューのみを制御します。This only controls queuing that occurs within the script host execution path. ASP.NET 要求キューなどの他のキューは有効なままで、この設定の影響を受けません。Other queues such as the ASP.NET request queue will still be in effect and unaffected by this setting. *バージョン 1.x の既定値は unbounded です。*The default for version 1.x is unbounded. 従量課金プランでのバージョン 2.x の既定値は 200 です。The default for version 2.x in a consumption plan is 200. 専用プランでのバージョン 2.x の既定値は unbounded です。The default for version 2.x in a dedicated plan is unbounded.
maxConcurrentRequestsmaxConcurrentRequests 100*100* 並列で実行される HTTP 関数の最大数。The maximum number of http functions that will be executed in parallel. これによりコンカレンシーを制御でき、リソース使用率の管理に役立ちます。This allows you to control concurrency, which can help manage resource utilization. たとえば、多くのシステム リソース (メモリ、CPU、ソケット) を消費する HTTP 関数があった場合、コンカレンシー率が高すぎると問題が発生します。For example, you might have an http function that uses a lot of system resources (memory/cpu/sockets) such that it causes issues when concurrency is too high. または、サードパーティのサービスに対して要求を送信する関数があり、その呼び出し速度を制限する必要がある場合です。Or you might have a function that makes outbound requests to a third party service, and those calls need to be rate limited. このような場合は、調整を適用することができます。In these cases, applying a throttle here can help. *バージョン 1.x の既定値は unbounded です。*The default for version 1.x is unbounded. 従量課金プランでのバージョン 2.x の既定値は 100 です。The default for version 2.x in a consumption plan is 100. 専用プランでのバージョン 2.x の既定値は unbounded です。The default for version 2.x in a dedicated plan is unbounded.
dynamicThrottlesEnableddynamicThrottlesEnabled true*true* この設定を有効にすると、要求処理パイプラインが、システム パフォーマンス カウンター (接続、スレッド、プロセス、メモリ、CPU など) を定期的にチェックし、カウンターのいずれかが組み込まれた上限閾値 (80%) を超えた場合は、カウンターが正常なレベルに戻るまで要求は 429 "Too Busy" 応答で拒否されます。When enabled, this setting causes the request processing pipeline to periodically check system performance counters like connections/threads/processes/memory/cpu/etc. and if any of those counters are over a built-in high threshold (80%), requests will be rejected with a 429 "Too Busy" response until the counter(s) return to normal levels. *バージョン 1.x の既定値は false です。*The default for version 1.x is false. 従量課金プランでのバージョン 2.x の既定値は true です。The default for version 2.x in a consumption plan is true. 専用プランでのバージョン 2.x の既定値は false です。The default for version 2.x in a dedicated plan is false.

出力Output

HTTP 要求送信者に応答するには、HTTP 出力バインドを使用します。Use the HTTP output binding to respond to the HTTP request sender. このバインドには、HTTP トリガーが必要です。このバインドを使用すると、トリガーの要求に関連付けられている応答をカスタマイズすることができます。This binding requires an HTTP trigger and allows you to customize the response associated with the trigger's request. HTTP 出力バインドが提供されていない場合、HTTP トリガーは、Functions 1.x では HTTP 200 OK と空の本文を返し、Functions 2.x では HTTP 204 No Content と空の本文を返します。If an HTTP output binding is not provided, an HTTP trigger returns HTTP 200 OK with an empty body in Functions 1.x, or HTTP 204 No Content with an empty body in Functions 2.x.

出力 - 構成Output - configuration

次の表は、function.json ファイルで設定したバインド構成のプロパティを説明しています。The following table explains the binding configuration properties that you set in the function.json file. C# クラス ライブラリには、function.json のこれらのプロパティに対応する属性プロパティはありません。For C# class libraries, there are no attribute properties that correspond to these function.json properties.

プロパティProperty 説明Description
typetype http に設定する必要があります。Must be set to http.
directiondirection out に設定する必要があります。Must be set to out.
namename 応答の関数コードで使用される変数名、または戻り値を使うことを示す $returnThe variable name used in function code for the response, or $return to use the return value.

出力 - 使用方法Output - usage

HTTP 応答を送信するには、言語標準の応答パターンを使います。To send an HTTP response, use the language-standard response patterns. C# またはで C# スクリプトでは、関数の戻り値の型を IActionResult または Task<IActionResult> にします。In C# or C# script, make the function return type IActionResult or Task<IActionResult>. C# の場合、戻り値の属性は必要ありません。In C#, a return value attribute isn't required.

応答の例のため、トリガー例を参照してください。For example responses, see the trigger example.

次の手順Next steps

Azure Functions のトリガーとバインドの詳細情報Learn more about Azure functions triggers and bindings