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

この記事では、Azure Functions プロキシ を構成および操作する方法について説明します。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.

バックエンドへの要求は、ポータルでプロキシの詳細ページの "要求の上書き" セクションを展開して変更することができます。Back-end requests can be modified in the portal by expading the request override section of the proxy detail page.

応答を変更する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.

バックエンドへの要求は、ポータルでプロキシの詳細ページの "応答の上書き" セクションを展開して変更することができます。Back-end requests can be modified in the portal by expading the response override section of the proxy detail page.

変数を使用するUse variables

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

ローカル関数を参照するReference local functions

localhost を使用して、往復のプロキシ要求なしで、同じ関数アプリ内の関数を直接参照することができます。You can use localhost to reference a function inside the same function app directly, without a roundtrip proxy request.

"backendurl": "https://localhost/api/httptriggerC#1" は、ローカルの HTTP トリガーされた関数をルート /api/httptriggerC#1 で参照します。"backendurl": "https://localhost/api/httptriggerC#1" will reference a local HTTP triggered function at the route /api/httptriggerC#1

注意

関数が "function、admin、または sys" の承認レベルを使用している場合は、元の関数 URL に従って code と clientId を指定する必要があります。If your function uses function, admin or sys authorization levels, you will need to provide the code and clientId, as per the original function URL. この場合、参照は "backendurl": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>" のようになります。In this case the reference would look like: "backendurl": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>"

要求のパラメーターを参照する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 response, 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.

プロキシのトラブルシューティングTroubleshoot Proxies

フラグ "debug":trueproxies.json 内の任意のプロキシに追加することで、デバッグ ログを有効にします。By adding the flag "debug":true to any proxy in your proxies.json you will enable debug logging. ログは、D:\home\LogFiles\Application\Proxies\DetailedTrace に格納され、高度なツール (Kudu) を使用してアクセスできます。Logs are stored in D:\home\LogFiles\Application\Proxies\DetailedTrace and accessible through the advanced tools (kudu). すべての HTTP 応答には、Proxy-Trace-Location ヘッダーと、ログ ファイルにアクセスするための URL も含まれます。Any HTTP responses will also contain a Proxy-Trace-Location header with a URL to access the log file.

true に設定した Proxy-Trace-Enabled ヘッダーを追加することによって、クライアント側からプロキシをデバッグできます。You can debug a proxy from the client side by adding a Proxy-Trace-Enabled header set to true. これにより、ファイル システムのトレースもログに記録され、応答のヘッダーとしてトレースの URL が返されます。This will also log a trace to the file system, and return the trace URL as a header in the response.

プロキシ トレースをブロックするBlock proxy traces

セキュリティ上の理由から、トレースを生成するためのサービスの呼び出しは許可しないことをお勧めします。For security reasons you may not want to allow anyone calling your service to generate a trace. ログイン資格情報なしでトレース コンテンツにアクセスすることはできませんが、トレースを生成するとリソースが消費され、Functions プロキシを使用していることが公開されます。They will not be able to access the trace contents without your login credentials, but generating the trace consumes resources and exposes that you are using Function Proxies.

proxies.json 内の特定のプロキシに "debug":false を追加することで、トレースを完全に無効にします。Disable traces altogether by adding "debug":false to any particular proxy in your proxies.json.

詳細な構成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.

ヒント

いずれのデプロイ方法もまだ設定していない場合は、ポータルで 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 プロキシの route プロパティ では、Function App ホスト構成の routePrefix プロパティは考慮されません。The route property in Azure Functions Proxies does not honor the routePrefix property of the Function App host configuration. /api のようなプレフィックスを含める場合は、route プロパティに含める必要があります。If you want to include a prefix such as /api, it must be included in the route property.

個々のプロキシを無効するDisable individual proxies

個々のプロキシを無効にするには、proxies.json ファイル内のプロキシに "disabled": true を追加します。You can disable individual proxies by adding "disabled": true to the proxy in the proxies.json file. これにより、matchCondidtion を満たす要求はすべて 404 を返します。This will cause any requests meeting the matchCondidtion to return 404.

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "Root": {
            "disabled":true,
            "matchCondition": {
                "route": "/example"
            },
            "backendUri": "www.example.com"
        }
    }
}

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 response body is set directly, so no backendUri property is needed. この例では、Azure Functions プロキシを使って API のモッキングを行う方法を説明しています。The example shows how you might use Azure Functions Proxies for mocking APIs.