Azure Functions プロキシの操作Work with Azure Functions Proxies

この記事では、Azure Functions Proxies を構成および操作する方法について説明します。This article explains how to configure and work with Azure Functions Proxies. この機能を使用すると、他のリソースによって実装される、関数アプリのエンドポイントを指定することができます。With this feature, you can specify endpoints on your function app that are implemented by another resource. これらのプロキシを使用して、大きな API を複数の関数アプリに分割できます (マイクロサービス アーキテクチャでのように)。その場合でも、クライアントには単一の API サーフェスとして表示されます。You can use these proxies to break a large API into multiple function apps (as in a microservice architecture), while still presenting a single API surface for clients.

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

注意

プロキシの実行には標準の Functions の料金が適用されます。Standard Functions billing applies to proxy executions. 詳細については、Azure Functions の価格に関するページを参照してください。For more information, see Azure Functions pricing.

プロキシを作成するCreate a proxy

このセクションでは、Functions ポータルでプロキシを作成する方法を示します。This section shows you how to create a proxy in the Functions portal.

  1. Azure Portal を開き、関数アプリに移動します。Open the Azure portal, and then go to your function app.
  2. 左側のウィンドウで、[新しいプロキシ] を選択します。In the left pane, select New proxy.
  3. プロキシの名前を指定します。Provide a name for your proxy.
  4. ルート テンプレートHTTP メソッドを指定して、この関数アプリで公開されるエンドポイントを構成します。Configure the endpoint that's exposed on this function app by specifying the route template and HTTP methods. これらのパラメーターは、HTTP トリガーの規則に従って動作します。These parameters behave according to the rules for [HTTP triggers].
  5. バックエンド URL を他のエンドポイントに設定します。Set the backend URL to another endpoint. このエンドポイントは、別の関数アプリ内の関数にすることも、他の任意の API にすることもできます。This endpoint could be a function in another function app, or it could be any other API. 静的な値である必要はありません。アプリケーション設定元のクライアント要求のパラメーターを参照することもできます。The value does not need to be static, and it can reference [application settings] and [parameters from the original client request].
  6. Create をクリックしてください。Click Create.

これで、プロキシが関数アプリの新しいエンドポイントになりました。Your proxy now exists as a new endpoint on your function app. クライアントの観点からは、Azure Functions の HttpTrigger と同じです。From a client perspective, it is equivalent to an HttpTrigger in Azure Functions. プロキシの URL をコピーし、任意の HTTP クライアントでテストすることで、新しいプロキシを試してみることができます。You can try out your new proxy by copying the Proxy URL and testing it with your favorite HTTP client.

要求と応答を変更するModify requests and responses

バックエンドに対する要求やバックエンドからの応答には、Azure Functions プロキシを使って変更を加えることができます。With Azure Functions Proxies, you can modify requests to and responses from the back end. この変換時には、「変数を使用する」で定義している変数を使うことができます。These transformations can use variables as defined in [Use variables].

バックエンドへの要求を変更するModify the back-end request

既定では、バックエンドへの要求は、元の要求のコピーとして初期化されます。By default, the back-end request is initialized as a copy of the original request. バックエンドの URL を設定することに加え、HTTP メソッドやヘッダー、クエリ文字列のパラメーターに変更を加えることができます。In addition to setting the back-end URL, you can make changes to the HTTP method, headers, and query string parameters. 変更後の値から、アプリケーション設定元のクライアント要求のパラメーターを参照することが可能です。The modified values can reference [application settings] and [parameters from the original client request].

現時点では、ポータルからバックエンドへの要求に変更を加えることはできません。Currently, there is no portal experience for modifying back-end requests. この機能を proxies.json から利用する方法については、「requestOverrides オブジェクトの定義」をご覧ください。To learn how to apply this capability from proxies.json, see [Define a requestOverrides object].

応答を変更するModify the response

既定では、クライアントへの応答は、バックエンドからの応答のコピーとして初期化されます。By default, the client response is initialized as a copy of the back-end response. 応答の状態コード、理由の文字列、ヘッダー、本文には、変更を加えることができます。You can make changes to the response's status code, reason phrase, headers, and body. 変更後の値から、アプリケーション設定元のクライアント要求のパラメーターバックエンドからの応答のパラメーターを参照することが可能です。The modified values can reference [application settings], [parameters from the original client request], and [parameters from the back-end response].

現時点では、ポータルから応答に変更を加えることはできません。Currently, there is no portal experience for modifying responses. この機能を proxies.json から利用する方法については、「responseOverrides オブジェクトの定義」をご覧ください。To learn how to apply this capability from proxies.json, see [Define a responseOverrides object].

変数を使用するUse variables

プロキシの構成は必ずしも静的である必要はありません。The configuration for a proxy does not need to be static. 条件に応じて元の要求やバックエンドからの応答、アプリケーション設定から得られる変数を使うことができます。You can condition it to use variables from the original request, the back-end response, or application settings.

要求のパラメーターを参照するReference request parameters

要求のパラメーターは、バックエンド URL プロパティの入力として、または要求や応答に加える変更の一部として使うことができます。You can use request parameters as inputs to the back-end URL property or as part of modifying requests and responses. パラメーターには、ベース プロキシの構成に指定されているルート テンプレートに由来するものもあれば、受信要求のプロパティに由来するものもあります。Some parameters can be bound from the route template that's specified in the base proxy configuration, and others can come from properties of the incoming request.

ルート テンプレートのパラメーターRoute template parameters

ルート テンプレートに使われているパラメーターは、名前で参照することができます。Parameters that are used in the route template are available to be referenced by name. パラメーター名は中かっこ ({}) で囲みます。The parameter names are enclosed in braces ({}).

たとえば、プロキシに /pets/{petId} のようなルート テンプレートがある場合、バックエンド URL には https://<AnotherApp>.azurewebsites.net/api/pets/{petId} のようにして、{petId} の値を含めることができます。For example, if a proxy has a route template, such as /pets/{petId}, the back-end URL can include the value of {petId}, as in https://<AnotherApp>.azurewebsites.net/api/pets/{petId}. ルート テンプレートが /api/{*restOfPath} のようにワイルドカードで終了している場合、値 {restOfPath} は受信要求の残りのパス セグメントの文字列表現になります。If the route template terminates in a wildcard, such as /api/{*restOfPath}, the value {restOfPath} is a string representation of the remaining path segments from the incoming request.

要求のパラメーター (その他)Additional request parameters

構成の値には、ルート テンプレートのパラメーターに加え、次の値を使うことができます。In addition to the route template parameters, the following values can be used in config values:

  • {request.method}: 元の要求に使われていた HTTP メソッド。{request.method}: The HTTP method that's used on the original request.
  • {request.headers.<HeaderName>}: 元の要求から読み取り可能なヘッダー。{request.headers.<HeaderName>}: A header that can be read from the original request. <HeaderName> は、読み取るヘッダーの名前に置き換えます。Replace <HeaderName> with the name of the header that you want to read. 該当するヘッダーが要求に含まれていない場合、この値は空の文字列になります。If the header is not included on the request, the value will be the empty string.
  • {request.querystring.<ParameterName>}: 元の要求から読み取り可能なクエリ文字列パラメーター。{request.querystring.<ParameterName>}: A query string parameter that can be read from the original request. <ParameterName> は、読み取るパラメーターの名前に置き換えます。Replace <ParameterName> with the name of the parameter that you want to read. 該当するパラメーターが要求に含まれていない場合、この値は空の文字列になります。If the parameter is not included on the request, the value will be the empty string.

バックエンドからの応答のパラメーターを参照するReference back-end response parameters

応答のパラメーターは、クライアントへの応答に加える変更の一部として使うことができます。Response parameters can be used as part of modifying the response to the client. 構成の値には、次の値を使うことができます。The following values can be used in config values:

  • {backend.response.statusCode}: バックエンドからの応答で返される HTTP 状態コード。{backend.response.statusCode}: The HTTP status code that's returned on the back-end response.
  • {backend.response.statusReason}: バックエンドからの応答で返される HTTP 理由文字列。{backend.response.statusReason}: The HTTP reason phrase that's returned on the back-end response.
  • {backend.response.headers.<HeaderName>}: バックエンドの応答から読み取り可能なヘッダー。{backend.response.headers.<HeaderName>}: A header that can be read from the back-end response. <HeaderName> は、読み取るヘッダーの名前に置き換えます。Replace <HeaderName> with the name of the header you want to read. 該当するヘッダーが要求に含まれていない場合、この値は空の文字列になります。If the header is not included on the request, the value will be the empty string.

アプリケーション設定を参照するReference application settings

関数アプリに対して定義されているアプリケーション設定を参照することもできます。その場合は、設定名をパーセント記号 (%) で囲みます。You can also reference application settings defined for the function app by surrounding the setting name with percent signs (%).

たとえば、https://%ORDER_PROCESSING_HOST%/api/orders のバックエンド URL で、"%ORDER_PROCESSING_HOST%" は ORDER_PROCESSING_HOST 設定の値に置き換えられます。For example, a back-end URL of https://%ORDER_PROCESSING_HOST%/api/orders would have "%ORDER_PROCESSING_HOST%" replaced with the value of the ORDER_PROCESSING_HOST setting.

ヒント

複数のデプロイまたはテスト環境がある場合は、バックエンド ホストのアプリケーション設定を使用してください。Use application settings for back-end hosts when you have multiple deployments or test environments. そうすることで、常にその環境の適切なバックエンドと通信することができます。That way, you can make sure that you are always talking to the right back end for that environment.

詳細な構成Advanced configuration

構成するプロキシは、関数アプリ ディレクトリのルートにある proxies.json ファイルに格納されます。The proxies that you configure are stored in a proxies.json file, which is located in the root of a function app directory. このファイルを手動で編集し、Functions でサポートされているいずれかのデプロイ方法を使用するときにアプリの一部としてデプロイできます。You can manually edit this file and deploy it as part of your app when you use any of the deployment methods that Functions supports. ファイルが処理されるようにするには、この機能を有効にしておく必要があります。The feature must be enabled for the file to be processed.

ヒント

いずれのデプロイ方法もまだ設定していない場合は、ポータルから proxies.json ファイルを編集することもできます。If you have not set up one of the deployment methods, you can also work with the proxies.json file in the portal. 目的の関数アプリに移動して [プラットフォーム機能] を選択し、[App Service エディター] を選択します。Go to your function app, select Platform features, and then select App Service Editor. これにより、関数アプリのファイル構造全体が表示され、変更を加えることができます。By doing so, you can view the entire file structure of your function app and then make changes.

Proxies.json は、名前付きプロキシとその定義から成るプロキシ オブジェクトによって定義されます。Proxies.json is defined by a proxies object, which is composed of named proxies and their definitions. エディターがサポートしていれば、必要に応じて JSON スキーマを参照してコード補完を行うことができます。Optionally, if your editor supports it, you can reference a JSON schema for code completion. サンプル ファイルは、次のようになります。An example file might look like the following:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

各プロキシには、上の例の proxy1 のようなフレンドリ名があります。Each proxy has a friendly name, such as proxy1 in the preceding example. 対応するプロキシ定義オブジェクトは、以下のプロパティによって定義されます。The corresponding proxy definition object is defined by the following properties:

  • matchCondition: 必須 - このプロキシの実行をトリガーする要求を定義するオブジェクト。matchCondition: Required--an object defining the requests that trigger the execution of this proxy. HTTP トリガーと共有される、次の 2 つのプロパティが含まれています。It contains two properties that are shared with [HTTP triggers]:
    • methods: プロキシが応答する HTTP メソッドの配列。methods: An array of the HTTP methods that the proxy responds to. 指定しない場合、プロキシはルートのすべての HTTP メソッドに応答します。If it is not specified, the proxy responds to all HTTP methods on the route.
    • route: 必須 - プロキシがどの要求 URL に応答するかを制御するルート テンプレートを定義します。route: Required--defines the route template, controlling which request URLs your proxy responds to. HTTP トリガーとは異なり、既定値はありません。Unlike in HTTP triggers, there is no default value.
  • backendUri: 要求のプロキシ先となる、バックエンド リソースの URL。backendUri: The URL of the back-end resource to which the request should be proxied. この値から、アプリケーション設定や元のクライアント要求のパラメーターを参照することが可能です。This value can reference application settings and parameters from the original client request. このプロパティが含まれていない場合、Azure Functions は HTTP 200 OK で応答します。If this property is not included, Azure Functions responds with an HTTP 200 OK.
  • requestOverrides: バックエンドへの要求に対する変換を定義するオブジェクト。requestOverrides: An object that defines transformations to the back-end request. requestOverrides オブジェクトの定義」をご覧ください。See [Define a requestOverrides object].
  • responseOverrides: クライアントへの応答に対する変換を定義するオブジェクト。responseOverrides: An object that defines transformations to the client response. responseOverrides オブジェクトの定義」をご覧ください。See [Define a responseOverrides object].

注意

ルート プロパティ Azure Functions Proxies では、Functions ホスト構成の routePrefix プロパティは考慮されません。The route property Azure Functions Proxies does not honor the routePrefix property of the Functions host configuration. /api のようなプレフィックスを含める場合は、ルート プロパティに含める必要があります。If you want to include a prefix such as /api, it must be included in the route property.

requestOverrides オブジェクトの定義Define a requestOverrides object

バックエンド リソースが呼び出されたときに要求に対して行う変更は、requestOverrides オブジェクトで定義します。The requestOverrides object defines changes made to the request when the back-end resource is called. このオブジェクトは、次のプロパティによって定義されます。The object is defined by the following properties:

  • backend.request.method: バックエンドを呼び出す際に使用される HTTP メソッドです。backend.request.method: The HTTP method that's used to call the back end.
  • backend.request.querystring.<ParameterName>: バックエンドの呼び出し時に設定できるクエリ文字列パラメーター。backend.request.querystring.<ParameterName>: A query string parameter that can be set for the call to the back end. <ParameterName> は、設定するパラメーターの名前に置き換えます。Replace <ParameterName> with the name of the parameter that you want to set. 空の文字列を指定した場合、このパラメーターはバックエンドへの要求に反映されません。If the empty string is provided, the parameter is not included on the back-end request.
  • backend.request.headers.<HeaderName>: バックエンドの呼び出し時に設定可能なヘッダー。backend.request.headers.<HeaderName>: A header that can be set for the call to the back end. <HeaderName> は、設定するヘッダーの名前に置き換えます。Replace <HeaderName> with the name of the header that you want to set. 空の文字列を指定した場合、このヘッダーはバックエンドへの要求に反映されません。If you provide the empty string, the header is not included on the back-end request.

アプリケーション設定や元のクライアント要求のパラメーターを値から参照することができます。Values can reference application settings and parameters from the original client request.

実際の構成の例を次に示します。An example configuration might look like the following:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>",
            "requestOverrides": {
                "backend.request.headers.Accept": "application/xml",
                "backend.request.headers.x-functions-key": "%ANOTHERAPP_API_KEY%"
            }
        }
    }
}

responseOverrides オブジェクトの定義Define a responseOverrides object

クライアントに返される応答に対して行う変更は、requestOverrides オブジェクトで定義します。The requestOverrides object defines changes that are made to the response that's passed back to the client. このオブジェクトは、次のプロパティによって定義されます。The object is defined by the following properties:

  • response.statusCode: クライアントに返される HTTP 状態コード。response.statusCode: The HTTP status code to be returned to the client.
  • response.statusReason: クライアントに返される HTTP 理由文字列。response.statusReason: The HTTP reason phrase to be returned to the client.
  • response.body: クライアントに返される本体の文字列表記。response.body: The string representation of the body to be returned to the client.
  • response.headers.<HeaderName>: クライアントへの応答時に設定可能なヘッダー。response.headers.<HeaderName>: A header that can be set for the response to the client. <HeaderName> は、設定するヘッダーの名前に置き換えます。Replace <HeaderName> with the name of the header that you want to set. 空の文字列を指定した場合、このヘッダーは応答に反映されません。If you provide the empty string, the header is not included on the response.

アプリケーション設定や元のクライアント要求のパラメーター、バックエンドからの応答のパラメーターを値から参照することができます。Values can reference application settings, parameters from the original client request, and parameters from the back-end response.

実際の構成の例を次に示します。An example configuration might look like the following:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "responseOverrides": {
                "response.body": "Hello, {test}",
                "response.headers.Content-Type": "text/plain"
            }
        }
    }
}

注意

この例では本文を直接設定しているため、backendUri プロパティは必要ありません。In this example, the body is being set directly, so no backendUri property is needed. この例では、Azure Functions プロキシを使って API のモッキングを行う方法を説明しています。The example shows how you might use Azure Functions Proxies for mocking APIs.

Azure Functions プロキシを有効にするEnable Azure Functions Proxies

現在、Azure Functions プロキシは既定で有効になっています。Proxies are now enabled by default! プレビュー版の古いバージョンのプロキシを使用し、プロキシを無効にしていた場合、プロキシを実行するために手動で有効化を 1 回行う必要があります。If you were using an older version of the proxies preview and disabled proxies, you will need to manually enable proxies once in order for proxies to execute.

  1. Azure Portal を開き、関数アプリに移動します。Open the Azure portal, and then go to your function app.
  2. [Function App の設定] を選択します。Select Function app settings.
  3. [Azure Functions プロキシの有効化 (プレビュー)][オン] に切り替えます。Switch Enable Azure Functions Proxies (preview) to On.

新機能が使用可能になったときに、ここに戻って、プロキシ ランタイムを更新することもできます。You can also return here to update the proxy runtime as new features become available.