Azure API Management - エラーレスポンスのカスタマイズ

目的

エラーレスポンスのヘッダ、ボディをカスタマイズする

API Managementで検出可能なエラー

組み込みの手順向けの定義済みエラー と ポリシーの定義済みのエラー があり、それぞれリンク先を参照

ポリシーの定義済みのエラーを検出するためには対応するポリシー（上記リンク先のsource）を定義しておく必要がある

エラーが発生すると、コントロールが on-error ポリシー セクションにジャンプし、エラー情報は context.LastError プロパティ内に格納される
context.LastError プロパティは lastError 参照

レスポンスヘッダ、ボディのカスタマイズ

組み込みの手順向けの定義済みエラー

以下、404Not Found のヘッダ、ボディをカスタマイズした例

<policies>
    <inbound>
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <choose>
            <when condition="@(context.LastError.Reason == "OperationNotFound")">
                <return-response>
                    <set-status code="404" />
                    <set-header name="Content-Type" exists-action="override">
                        <value>application/json</value>
                    </set-header>
                    <set-body>@{
                        return new JObject(
                            new JProperty("type", "error-type-1"),
                            new JProperty("reason", context.LastError.Reason.ToString()),
                            new JProperty("message", context.LastError.Message.ToString())
                        ).ToString();
                    }</set-body>
                </return-response>
            </when>
        </choose>
        <base />
    </on-error>
</policies>

組み込みの手順向けの定義済みエラーのReasonを条件にし、
set-headerでヘッダ情報の上書き、set-bodyでボディの設定を行っている

set-headerの詳細は HTTP ヘッダーの設定 参照

set-bodyの詳細は 本文の設定 参照

上記はcontext.LastError プロパティにアクセスするために set-body に API Management ポリシー式 を使用しているが、固定値のみで構成する場合は以下のように定義できる

<set-body>Hello world!</set-body>

<set-body>{
    "statusCode": 404,
    "message": "Not Found"
}</set-body>

以下、カスタマイズしたレスポンス結果

ポリシーの定義済みのエラー

以下、504 Gateway Timeout のヘッダ、ボディをカスタマイズした例

<policies>
    <inbound>
        <base />
    </inbound>
    <backend>
        <forward-request timeout="10" fail-on-error-status-code="true" />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <choose>
            <when condition="@(context.LastError.Reason == "Timeout")">
                <return-response>
                    <set-status code="504" />
                    <set-header name="Content-Type" exists-action="override">
                        <value>application/json</value>
                    </set-header>
                    <set-body>@{
                        return new JObject(
                            new JProperty("type", "error-type-2"),
                            new JProperty("reason", context.LastError.Reason.ToString()),
                            new JProperty("message", context.LastError.Message.ToString())
                        ).ToString();
                    }</set-body>
                </return-response>
            </when>
        </choose>
        <base />
    </on-error>
</policies>

ポリシーの定義済みのエラー のsourceにあるポリシーを定義する必要がある
今回の場合は forward-request でタイムアウト時間10秒、fail-on-error-status-codeで on-error セクションへのジャンプを有効にしている
その他詳細については forward-request 参照

以下、カスタマイズしたレスポンス結果