障害の処理

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge ドキュメントを表示する

API プロキシがアプリからのリクエストを処理しているときには、さまざまなエラーが発生する可能性があります。たとえば、バックエンド サービスとの通信中に API プロキシでネットワークの問題が検出される、アプリが期限切れの認証情報を提示する、リクエスト メッセージの形式に誤りがあるなどの問題が発生する可能性があります。

クライアント アプリが API プロキシを呼び出した後でエラーが発生した場合、エラー メッセージがクライアントに返されます。デフォルトでは、詳細や説明のない意味不明なエラー メッセージがクライアントに返されることがよくあります。ただし、デフォルトのエラー メッセージをよりわかりやすいカスタム メッセージに置き換え、さらに追加の HTTP ヘッダーなどでメッセージを補足したい場合は、カスタム障害処理を Apigee で設定する必要があります。

また、カスタム障害処理では、エラー発生時のメッセージ ロギングなどの機能も追加できます。

ヒント: 障害処理は、API プロキシ開発の主要なアーキテクチャ設計タスクです。時間をかけて、エラーをいつどのように処理するかを検討し、エラー メッセージの内容を決定し、エラー メッセージの形式を設計することが重要です。このような事項を検討した後（または検討の際）に、このトピックを参考にして、各自のカスタム障害処理を実装できます。

API プロキシでのカスタムエラー処理の実装について説明する前に、エラー発生する仕組みと、API プロキシがエラーに対応する仕組みを理解しておくと役に立ちます。

動画

障害処理の詳細については、次の動画をご覧ください。

動画	説明
障害処理とエラーフローの概要	障害処理の詳細と、API プロキシでエラーが発生した場合の動作について説明します。
障害ルールを使用した障害の処理	障害ルールを使用して障害を処理する方法について説明します。
RaiseFault ポリシーを使用したカスタム障害の生成	RaiseFault ポリシーを使用して API の実行中にカスタム障害を生成します。
API プロキシとターゲット エンドポイントでの障害ルールの定義	API プロキシとターゲット エンドポイントで障害ルールを定義し、その違いを理解します。
障害ルールの実行順序について	API プロキシとターゲット エンドポイントでの障害ルールの実行順序を理解します。
デフォルトの障害ルールの定義	デフォルトの障害ルールを定義して API の一般的なエラーを処理します。

エラーが発生する仕組み

まず、エラーが発生する仕組みについて説明します。エラーが発生する仕組みを理解しておくと、カスタムエラー処理を実装するさまざまな状況に備えて計画する際に役立ちます。

自動エラー

API プロキシは、次の場合にエラーを自動的にスローします。

• ポリシーによりエラーがスローされる場合。たとえば、API 呼び出しによって期限切れのキーが送信されると、VerifyAPIKey ポリシーによりエラーが自動的にスローされます。また、API 呼び出しの数が特定の上限を超えると、Quota ポリシーまたは SpikeArrest ポリシーによりエラーがスローされます（ポリシーによりスローされる可能性があるエラーのタイプについては、ポリシーエラー リファレンスをご覧ください）。
• ルーティング エラーなど、API プロキシのメッセージ フローに問題がある場合。
• プロトコル レベルの障害が原因の HTTP エラー、TLS / SSL エラー、ターゲット サービスの利用不可など、バックエンド障害が発生した場合。
• メモリ不足例外など、システムレベルの障害が発生した場合。

これらのエラーの詳細については、後述する障害の分類をご覧ください。

カスタムエラー

自動エラーが生成されない状況（レスポンスに unavailable という語が含まれている場合や、HTTP ステータス コードが 201 より大きい場合など）で、カスタムエラーをスローすることがあります。このためには、API プロキシフローの適切な位置に RaiseFault ポリシーを追加します。

RaiseFault ポリシーは、他のポリシーと同様に API プロキシフローに追加できます。次のプロキシ構成例では、Raise-Fault-1 ポリシーが TargetEndpoint レスポンスに接続されています。ターゲット サービスからのレスポンスに unavailable というテキストが含まれていると、RaiseFault ポリシーが実行され、エラーがスローされます。

<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>Raise-Fault-1</Name>
      <Condition>message.content Like "*unavailable*"</Condition>
    </Step>
  </Response>

これは、カスタムエラーをスローできることを示すことを目的とした例です。RaiseFault ポリシーの詳細については、FaultRule ポリシーと RaiseFault ポリシーで説明します。

他の例については、こちらの Apigee コミュニティの投稿をご覧ください。

• RaiseFault で JavaScript 変数を参照する

エラーが発生した場合に API プロキシが行う処理

ここでは、プロキシによってエラーがスローされた場合の動作について説明します。

プロキシ パイプラインの終了

API プロキシでエラーが発生すると、その発生方法に関係なく、通常のフロー パイプラインが終了し、エラー状態になり、クライアント アプリにエラー メッセージが返されます。API プロキシがエラー状態になると、処理を通常のフロー パイプラインに戻すことはできません。

たとえば、ProxyEndpoint リクエストで API プロキシのポリシーが次の順序で指定されているとします。

1. Verify API Key
2. Quota
3. JSON to XML

API キーの検証中にエラーが発生した場合、API プロキシはエラー状態になります。Quota ポリシーと JSON to XML ポリシーは実行されません。また、プロキシは TargetEndpoint に進まず、クライアント アプリに対してエラー メッセージが返されます。

FaultRule の確認

エラー状態の API プロキシは、デフォルトのエラー メッセージをクライアント アプリに返す前に、API プロキシ構成に次の項目が（次の順序で）存在するかどうかを確認します。

1. <FaultRules> セクション。定義されている特定の条件に基づいてカスタムエラー メッセージ（およびその他のポリシー）をトリガーするロジックが含まれています。
2. <DefaultFaultRule> セクション。次の場合にデフォルトのエラー メッセージをトリガーします。
   • <FaultRules> が定義されていない。
   • 既存の <FaultRules> が実行されていない。
   • <AlwaysEnforce> 要素が true に設定されている。

基本的に、API プロキシでは、カスタムエラー メッセージを返して他のロジックをトリガーできます。プロキシは、これらのセクションを検出できない場合、またはセクションが存在してもカスタム障害がトリガーされなかった場合には、Apigee で生成されたデフォルト メッセージを送信します。

簡単な障害処理の例

サンプル: 実際に試して学ぶ
簡単な障害処理の例の実際の動作を確認するには、Apigee GitHub サンプルにあるこの実際に試して学ぶ例を確認してください。リポジトリのクローンを作成し、そのトピックの手順に沿って操作するだけです。いつでもこのセクションに戻って簡単な障害処理の実装方法の詳細を確認できます。

最初は、API プロキシの呼び出しに必要な API キーが含まれていない簡単な例です。デフォルトでは、次のレスポンスがクライアント アプリに返されます。

HTTP/1.1 401 Unauthorized
Date: Wed, 20 Jul 2016 19:19:32 GMT
Content-Type: application/json
Content-Length: 150
Connection: keep-alive
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

API ユーザーがエラー メッセージを理解できる場合とできない場合があります。多くのデフォルト エラーはわかりにくく、解釈するのが困難です。

API デベロッパーの判断で、エラー メッセージを最終的に受け取るユーザーのニーズに対応するためにこのメッセージを変更できます。これは、デベロッパーが iOS アプリ デベロッパーの場合でも、独自のエラー メッセージ形式の要件がある内部テストグループの場合でも同様です。

ここでは、カスタムエラー メッセージを作成してこのエラーを処理する基本的な例を示します。この例で必要なものは、1）カスタム メッセージを定義するポリシーと、2）プロキシがエラー状態になったときにポリシーを実行する FaultRule です。

1. カスタム メッセージを定義するポリシーを作成する

まず、カスタムエラー メッセージを定義するポリシーを作成します。ペイロードとオプションの HTTP ヘッダー（ステータス コードや理由フレーズなど）を設定できる AssignMessage ポリシーなどの任意のタイプのポリシーを使用できます。この場合は、AssignMessage ポリシーが最適です。メッセージ ペイロードの制御、さまざまな HTTP ステータス コードの設定、さまざまな HTTP 理由フレーズの設定、HTTP ヘッダーの追加を行うことができます。

ポリシーをフローに接続する必要はありません。ポリシーを作成するの説明に沿ってポリシーを作成してください。

次の動作を行うAssignMessage ポリシーの例を以下に示します。

• JSON メッセージを返す。
• HTTP ステータス コード 911 を設定する（これは明らかに存在しないステータス コードで、柔軟に対処できることを示すためのものです）。このステータス コードは HTTP ヘッダーに表示されます。
• HTTP 理由フレーズを設定する（これは、この API キー欠落エラーを示すためにデフォルトの Unauthorized 理由フレーズを置き換えます）。理由フレーズは、HTTP ヘッダーのステータス コードの横に表示されます。
• invalidKey という新しい HTTP ヘッダーを作成して入力します。

<AssignMessage async="false" continueOnError="false" enabled="true" name="invalid-key-message">
    <DisplayName>Invalid key message</DisplayName>
    <Set>
        <Payload contentType="application/json">{"Citizen":"Where's your API key? I don't see it as a query parameter"}</Payload>
        <StatusCode>911</StatusCode>
    </Set>
    <Add>
        <Headers>
            <Header name="invalidKey">Invalid API key! Call the cops!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

このポリシーが実行されると、次のようなレスポンスがアプリに返されます。これを前に示したデフォルトのレスポンスと比較してください。

HTTP/1.1 911 Rejected by API Key Emergency Services
Date: Wed, 20 Jul 2016 18:42:36 GMT
Content-Type: application/json
Content-Length: 35
Connection: keep-alive
invalidKey: Invalid API key! Call the cops!
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"Citizen":"Where's your API key? I don't see it as a query parameter."}

わずかな変更ですが、どのような処理が可能であるかがわかります。少なくとも、メッセージを受け取ったデベロッパーは、クエリ パラメータに API キーを含めるのを忘れたことに気づきます。

では、このポリシーはどのように実行されるのでしょうか。次のセクションで説明します。

2. ポリシーをトリガーする <FaultRule> を作成する

プロキシ構成の <ProxyEndpoint> または <TargetEndpoint> セクションに、1 つ以上の個別の <FaultRule> セクションを含む <FaultRules> XML ブロックを追加します。各 FaultRule は、処理する個別のエラーを表します。この簡単な例では、FaultRule の構成を示す目的で FaultRule を 1 つだけ使用しています。

また、FaultRule が実行されない場合にカスタムの一般エラー メッセージを提供するため、<DefaultFaultRule> を追加します。

例

<ProxyEndpoint name="default">
...
    <FaultRules>
       <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

要点:

• FaultRule は、ProxyEndpoint で定義されています。これは重要です。ProxyEndpoint と TargetEndpoint に FaultRule を配置する方法については後述します。
• <Name>: 実行するポリシーの名前。この名前は、前のポリシーの例で示されているとおり、親要素のポリシーの name 属性から取得されます。

• <Condition>: Apigee は条件を評価し、条件が true である場合にのみこのポリシーを実行します。true と評価される FaultRule が複数存在する場合は、true である最初の FaultRule が実行されます（重要: FaultRule の評価順序は、複数の FaultRule と実行ロジックのセクションで説明しているとおり、TaegetEndpoint では 上から下、ProxyEndpoint では下から上と異なります）。条件を指定しない場合、FaultRule は自動的に true になります。ただし、これはベスト プラクティスではありません。各 FaultRule には独自の条件を指定することをおすすめします。

  注: 後で説明するように、Step には、ポリシーが実行されるかどうかを決める独自の「内部」条件を設定できます（その詳細については、複数の FaultRule と実行ロジック セクションをご覧ください）。ただし、Step の条件は FaultRule が実行されるかどうかとは無関係です。Apigee では、どの FaultRule が実行されるかを決定するために、外側の FaultRule 条件のみが考慮されます。

• <DefaultFaultRule>: カスタム FaultRule が実行されない場合は <DefaultFaultRule> が実行され、デフォルトの意味不明な Apigee 生成メッセージではなく、より一般的なカスタム メッセージが送信されます。<DefaultFaultRule> に <Condition> を指定することもできますが、ほとんどの場合は含めません。これは、どのような場合でも実行できる最後の手段とするためです。

  一般に DefaultFaultRule は、予期しないエラーが発生した場合に汎用エラー メッセージを返すために使用されます。この例として、テクニカル サポートの連絡先情報を含むメッセージがあります。こうしたデフォルト レスポンスには、デベロッパーにわかりやすい情報を提供すると同時に、システムの改ざんに悪用されかねないバックエンド URL などの情報を開示しないという、2 つの目的があります。

複数の FaultRule と実行ロジック

サンプル: 実際に試して学ぶ
複数の FaultRule を説明する簡単なサンプルを実際に使い始めたい場合は、Apigee GitHub サンプルで実際に試して学ぶ例を確認してください。リポジトリのクローンを作成し、そのトピックの手順に沿って操作するだけです。いつでもこのセクションに戻って、動作する仕組みの詳細を確認できます。

簡単な障害処理の例のセクションでは、1 つの FaultRule と条件の簡単な例を使用しました。実際の API プロジェクトでは、発生する可能性のあるすべてのエラーを考慮して、<ProxyEndpoint> と <TargetEndpoint> の両方に複数の FaultRule と 1 つの DefaultFaultRule を設定する可能性があります。それでも最終的には、API プロキシがエラー状態になると、1 つの FaultRule のみが実行されます。

このセクションでは、Apigee が FaultRule の処理で使用するロジックについて説明します。実行する 1 つの FaultRule にそのロジックがどのように到達するかということから、「内側の」 Step 条件の FaultRule がトリガーされたときにその条件がどのように処理されるかということまで説明します。また、このセクションでは <ProxyEndpoint> と <TargetEndpoint> の両方で FaultRule を定義するタイミングの目安を示し、FaultRule と RaiseFault ポリシーの関係についても説明します。

FaultRule の実行

注: 外側の条件と内側のの条件

このトピックでは、外側の条件と内側の条件について説明します。これらは、FaultRule 条件や Step 条件と考えることもできます。この違いが重要です。外側の FaultRule 条件と内側の Step 条件が指定されている FaultRule の例を次に示します。このセクションでは、その違いについて説明します。

<FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <!-- Inner (Step) condition. Only gets executed if
                     the FaultRule is executed. -->
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <!-- Outer (FaultRule) condition. Apigee evaluates this
                 to determine whether or not to execute
                 the FaultRule. -->
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>

API プロキシがエラー状態になった時点で Apigee が使用するロジックを次に簡潔に説明します。FaultRule の評価は、ProxyEndpoint と TargetEndpoint で若干違いがあります。

1. Apigee では、エラーが発生した場所に応じて、ProxyEndpoint または TargetEndpoint で FaultRule を評価します。
   • ProxyEndpoint - Apigee は、構成 XML で下の <FaultRule> から上に向かって、各 <FaultRule> の <Condition>（内部の <Step> 条件ではなく外側の条件）を評価します。
   • TargetEndpoint - Apigee は、構成 XML で上の <FaultRule> から下に向かって、各 <FaultRule> の <Condition>（内部の <Step> 条件ではなく外側の条件）を評価します。
2. 条件が true になっている最初の FaultRule を実行します。FaultRule に条件がない場合はデフォルトで true になります。
   • FaultRule が実行されると、FaultRule 内のすべての Step が XML 構成の上から下へ順に評価されます。条件のない Step は自動的に実行され（ポリシーが実行されます）、評価される <Condition> を含む Step が実行されます（code と評価される条件は実行されません）。

   • FaultRule が実行されても FaultRule の Step が 1 つも実行されない（条件が code と評価された）場合、Apigee で生成されたデフォルトのエラー メッセージがクライアント アプリに返されます。Apigee によりその 1 つの FaultRule がすでに実行されているため、<DefaultFaultRule> は実行されません。

     注: 例外は、<DefaultFaultRule> に子要素 <AlwaysEnforce>true</AlwaysEnforce> がある場合です。この場合は、FaultRule が実行されていても、DefaultFaultRule が実行されます。

     ただし、これに該当しない例外も 1 つあります。DefaultFaultRule 以外の FaultRule が RaiseFault ポリシーを呼び出す場合は、<DefaultFaultRule> タグの <AlwaysEnforce> 要素が true でも、DefaultFaultRule は実行されません。

3. FaultRule が 1 つも実行されない場合、<DefaultFaultRule> があれば、Apigee はそれを実行します。

インライン コメント付きの例を次に示します。

ProxyEndpoint の実行

ProxyEndpoint の FaultRule は下から上の順に評価されるため、次の例の最後の FaultRule から読み取りを開始し、上に移動します。最後に位置する DefaultFaultRule を確認してください。

<ProxyEndpoint name="default">
...
    <FaultRules>
<!-- 3. This FaultRule is automatically TRUE, because there's no outer
     condition. But because the FaultRule just below this got
     executed (bottom-to-top evaluation in a ProxyEndpoint), Apigee
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed.
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
<FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 1. Because this is the ProxyEndpoint, Apigee looks at this FaultRule
     first. But let's say this FaultRule is FALSE. A policy did not
     throw a FailedToResolveAPIKey error. Apigee moves UP to check
     the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed.
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Apigee has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

TargetEndpoint の実行

TargetEndpoint の FaultRule は上から下の順に評価されるため、次の例の最初の FaultRule から読み取りを開始し、下に移動します。最後に位置する DefaultFaultRule を確認してください。

<TargetEndpoint name="default">
...
    <FaultRules>
<!-- 1. Because this is the TargetEndpoint, Apigee looks at this FaultRule
     first. Let's say this FaultRule is FALSE.
     A policy did not throw a FailedToResolveAPIKey error.
     Apigee moves down to the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed.
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
        <FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 3. This FaultRule is automatically TRUE, because there's no outer
     condition. But because the FaultRule just above this got
     executed (top-to-bottom evaluation in a TargetEndpoint), Apigee
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed.
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Apigee has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

障害ルールの順序

前の例からわかるように、ProxyEndpoint と TargetEndpoint のいずれでエラーが発生するかに応じて FaultRule を配置する順序が重要です。

例:

ProxyEndpoint での順序	TargetEndpoint での順序
次の例では、下から上の順に評価されるため、FaultRule 3 が実行される場合、FaultRule 2 と 1 は評価されません。 5. FaultRule 1: FALSE 4. FaultRule 2: TRUE 3. FaultRule 3: TRUE 2. FaultRule 4: FALSE 1. FaultRule 5: FALSE	次の例では、上から下の順に評価されるため、FaultRule 2 が実行される場合、FaultRule 3、4、5 は評価されません。 1. FaultRule 1: FALSE 2. FaultRule 2: TRUE 3. FaultRule 3: TRUE 4. FaultRule 4: FALSE 5. FaultRule 5: FALSE

含めるポリシー

ポリシーを Step に配置することにより、FaultRule からポリシーを実行できます。たとえば、AssignMessage ポリシーを実行してクライアント アプリへのレスポンスの形式を設定し、MessageLogging ポリシーでメッセージをログに記録できます。ポリシーは、配置されている順（XML の上から下）に実行されます。

障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）

この見出しは一見同じことを繰り返しているようですが、これには、ポリシーの continueOnError 属性に応じて、プロキシエラーによって API プロキシがエラー状態になる場合とならない場合があることを意識したニュアンスが込められています。

言い換えると、API プロキシでは、プロキシがエラー状態になった場合にのみ <FaultRules> と <DefaultFaultRule> が評価されます。つまり、FaultRule 条件が true に評価されても、プロキシがエラー状態でない場合、FaultRule はトリガーされません。

ただし、エラーが発生してもプロキシがエラー状態にならない例があります。どのポリシーでも、continueOnError という親要素に属性を設定できます。この属性は、ポリシーが失敗した場合にプロキシがエラー状態になるかどうかを決定するため、障害処理において非常に重要です。ほとんどの場合、デフォルトの continueOnError="false" を使用します。このデフォルト設定では、ポリシーが失敗した場合にプロキシがエラー状態になり、カスタムエラー処理がトリガーされます。ただし、（Service Callout の失敗によりプロキシの実行を停止したくない場合などに）continueOnError="true" を使用すると、ポリシーが失敗した場合にエラー状態にならず、プロキシは FaultRule をチェックしません。

continueOnError="true" が設定されている場合のエラーロギングの詳細については、現在のフロー内でのポリシー障害の処理をご覧ください。

FaultRule を定義する場所: ProxyEndpoint または TargetEndpoint

API プロキシでエラーが発生した場合、そのエラーは、<ProxyEndpoint>（クライアント アプリからのリクエストまたはクライアント アプリへのレスポンス）か、<TargetEndpoint>（ターゲット サービスへのリクエストまたはターゲット サービスからのレスポンス）のいずれかで発生しています。エラーが発生した場所がどこであっても、Apigee はそこで FaultRules を探します。

たとえば、ターゲット サーバーを利用できない（HTTP ステータス コード 503）場合、API プロキシは <TargetEndpoint> レスポンスでエラー状態となり、通常の API プロキシフローは <ProxyEndpoint> に進みません。FaultRule が <ProxyEndpoint> でのみ定義されている場合、そのエラーは処理されません。

もう 1 つ例を示します。<ProxyEndpoint> レスポンスの RaiseFault ポリシーによってエラーがトリガーされた場合、<TargetEndpoint> の FaultRule は実行されません。

注: FaultRule の実行セクションで説明したとおり、FaultRule は次の順に評価されます。「外側」の条件が true と評価される最初の FaultRule が実行されます。

• ProxyEndpoint: 下から上。XML 構成の最後の FaultRule が最初に実行されます。
• TargetEndpoint: 上から下。XML 構成の最初の FaultRule が最初に実行されます。

FaultRule ポリシーと RaiseFault ポリシー

障害ルールと RaiseFault ポリシーは、一見すると障害処理を実行する別の方法と思われるかもしれません。ある意味ではそのとおりです。ただし、これらは連携もします。このセクションでは、この 2 つの関係について説明します。この関係を理解しておくと、特に両方を使用して障害処理を設計する場合に役立ちます。

概要:

• 障害ルールは、API プロキシがエラー状態になると必ず評価されます。

• RaiseFault ポリシーは、エラーが発生しない場合に API プロキシをエラー状態にする方法です。

  たとえば、ターゲット サービスからのレスポンスの HTTP ステータス コードが 200 より大きい場合にエラーをスローするには、レスポンス フローに RaiseFault ポリシーを追加します。これは次のようになります。

  <TargetEndpoint name="default">
      <PreFlow name="PreFlow">
  ...
          <Response>
              <Step>
                  <Name>Raise-Fault-1</Name>
  <!-- If the condition is true, the Raise-Fault-1 policy gets executed -->
                  <Condition>(response.status.code GreaterThan "200")</Condition>
              </Step>
          </Response>
  

  RaiseFault ポリシーは、クライアント アプリにもエラー メッセージを送信します。

RaiseFault ポリシーによってエラーがトリガーされるとどうなるでしょうか。プロキシがエラー状態になるのでしょうか。FaultRule が実行される可能性があるのでしょうか。この場合、状況が多少複雑になります。RaiseFault ポリシーによってエラー メッセージが返され、さらに FaultRule がトリガーされてエラー メッセージが返された場合、クライアント アプリには何が返されるのでしょうか。

• FaultRule または DefaultFaultRule は RaiseFault ポリシーの後で実行されるため、FaultRule レスポンス データが優先されます。
• RaiseFault ポリシーのレスポンス データ（ステータス コード、理由フレーズ、メッセージ ペイロード）は、そのデータが FaultRule または DefaultFaultRule によって設定されていない場合に使用されます。
• RaiseFault ポリシーと FaultRule の両方でカスタム HTTP ヘッダーが追加された場合、両方がレスポンスに含まれます。ヘッダー名が重複する場合は、複数値のヘッダーが作成されます。

RaiseFault ポリシーと FaultRule によって設定される内容とクライアント アプリに返される内容の例を次に示します。これらのサンプルは、ベスト プラクティスではなく簡潔に設計されたものです。

クライアント アプリの受信内容: Status Code: 468 Reason Phrase: Something happened Payload: {"Whoa":"Sorry."} Header: errorNote: woops,gremlins

<- 障害ルールポリシーによって次のように設定されます: Status Code: [none] Reason Phrase: Something happened Payload: {"Whoa":"Sorry."} Header: errorNote: gremlins

<- RaiseFault ポリシーによって次のように設定されます: Status Code: 468 Reason Phrase: Can't do that Payload: {"DOH!":"Try again."} Header: errorNote: woops

注: <DefaultFaultRule> に子要素 <AlwaysEnforce>true</AlwaysEnforce> が含まれている場合、他の FaultRule が実行されている場合でも、DefaultFaultRule は常に実行されます。DefaultFaultRule は最後に実行されるため、DefaultFaultRule 内のポリシーによって設定されたペイロードやヘッダーがクライアントに返されます。

条件の作成

条件は、FaultRule 実行の基本部分です。FaultRule の条件は、条件フローや RaiseFault の条件など、Apigee における他の条件と同じ方法で作成できます。

以降、このセクションでは、次に示す障害ルールの例について説明します。このルールには、外側の FaultRule 条件と内側の Step 条件が含まれています。

<FaultRule name="invalid_key_rule">
    <Step>
        <Name>invalid-key-message</Name>
        <Condition>oauthV2.Verify-API-Key-1.failed = true</Condition>
    </Step>
    <Condition>fault.name = "FailedToResolveAPIKey"</Condition>
</FaultRule>

ポリシーエラーに固有の変数

fault.name 変数と {policy_namespace}.{policy_name}.failed 変数は、ポリシーがエラーをスローした場合に使用できます。

fault.name

ポリシーが失敗した場合は、fault.name 変数を使用して条件内のエラーをキャッチします。例:

<Condition>fault.name = "policy_error_name"</Condition>

エラー名は、デフォルトのエラー メッセージに表示されます。たとえば、次の例では、障害名は FailedToResolveAPIKey です。この場合、fault.name というフロー変数が値 FailedToResolveAPIKey に設定されています。

{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

したがって、条件は次のようになります。

<Condition>fault.name = "FailedToResolveAPIKey"</Condition>

ポリシーエラーの一覧については、ポリシーエラー リファレンスをご覧ください。

{policy_namespace}.{policy_name}.failed

*.failed 変数は、ポリシーが失敗した場合に使用できます。さまざまなポリシーの *.failed 変数の例を次に示します。ポリシーの名前空間については、各ポリシー リファレンス トピックのフロー変数をご覧ください。

• RaiseFault ポリシー: raisefault.failed（すべての RaiseFault ポリシーで同じ）
• VerifyAPIKey ポリシー: oauthV2.{policy_name}.failed（oauthV2.Verify-API-Key-1.failed など）
• Quota ポリシーと SpikeArrest ポリシー: ratelimit.{policy_name}.failed（ratelimit.Quota-1.failed など）

使用可能なその他の変数

API プロキシがエラー状態になった場合、条件で次の変数のみを使用できます。

• エラーになったポリシーの変数。
• エラーが発生した時点で存在している HTTP メッセージ変数。たとえば、レスポンスでエラーがスローされた場合、<TargetEndpoint> の FaultRule は HTTP データ response.status.code、message.content、error.content などを使用できます。Quota ポリシーがエラーになった場合は、変数 ratelimit.{quota_policy_name}.exceed.count を使用できます。Debug ツールとポリシー リファレンスを使用すると、使用可能な変数と HTTP データを把握できます。

詳細

• 条件: 条件のリファレンスおよびフロー変数と条件

  注: < や > 演算子を条件内で使用すると、検証エラーが発生します（不正な XML）。条件リファレンスのトピックに記載されている LesserThan や GreaterThan など、言語表記の演算子を使用してください。
• エラー: ポリシーエラー リファレンス。
• 変数: フロー変数リファレンス。各ポリシーで使用可能な変数については、それぞれのポリシー リファレンス ページをご覧ください。

障害処理のベストプラクティス

障害処理は、API プロキシ開発の主要なアーキテクチャ設計タスクです。時間をかけて、エラーをいつどのように処理するかを検討し、エラー メッセージの内容を決定し、エラー メッセージの形式を設計することが重要です。このような事項を検討した後（または検討中）に、以下のベスト プラクティスを使用して、各自のカスタム障害処理を実装できます。

障害処理を設計して作成する際のベスト プラクティスは、次のとおりです。

• FaultRule では、任意のタイプのポリシーを指定できます。最も一般的なパターンは、AssignMessage ポリシーを使用して、保留中のエラー レスポンスの特定のアイテムを設定することです。また、AssignMessage を使用して、他の目的で使用される変数を設定することもできます。たとえば、PostClientFlow または FlowHook で実行されるロギング ポリシーによって参照される変数などです。また、特定の障害条件で特定のエラーをログに記録する場合は、MessageLogging ポリシーや ServiceCallout ポリシーなどを使用してメッセージをログに記録することを検討してください。
• RaiseFault ポリシーを FaultRule 内の Step として指定しないでください。ペイロード、ヘッダー、ステータス コードなどのメッセージ要素を設定または変更するには、AssignMessage ポリシーを使用することをおすすめします。
• FaultRule ごとに、または最後に評価された FaultRule を除くすべての FaultRule に、<FaultRule> 要素の子として接続された外側の <Condition> を指定します。明示的な条件が指定されていない FaultRule の実行条件は、暗黙的に true と評価されます。<Step> 要素の子として接続されている <Condition> 要素は、FaultRule の実行条件が true と false のいずれに評価されるかの決定には使用されません。Step 条件は、それを含む FaultRule が Apigee によって実行された後でのみ評価されます。FaultRule では、一般に、AssignMessage（またはその他の）ポリシーを持つ複数の Step があり、各 Step に Step 条件が設定されます。

• 同じタイプの複数のポリシー（たとえば、複数の Quota ポリシー）でエラーを処理するには、発生する可能性があるポリシーエラーごとに 1 つの FaultRule を作成し、Step に接続された条件を使用して個々のエラーを区別します。たとえば、QuotaViolation などの Quota ポリシーでエラーを処理する FaultRule を作成し、InvalidApiKey 用に別の FaultRule を作成します（ポリシーエラーについては、ポリシーエラー リファレンスをご覧ください。処理が必要なエラーが他に見つかった場合は、後で戻って FaultRule に追加できます。反復処理しても問題はありませんが、プロキシの再デプロイが必要になります）。このアプローチでは、エラーをスローするポリシーに関係なく同じタイプのエラーをキャッチできるため、FaultRule XML が効率的になります。

  内側の Step 条件を使用すると、よりきめ細かく制御できるようになります。たとえば、リクエスト フローで 2 つのポリシーに個別のデベロッパー割り当てとグローバル割り当ての両方を適用する場合は、QuotaViolation エラー（いずれかの条件発生時に割り当てを超えた場合にスローされます）の発生時にトリガーされるよう外側の FaultRule 条件を設定します。次に、両方の Quota ポリシーの特定の exceed.count 変数を評価する Step 条件を設定します。関連するエラー（デベロッパー割り当てまたはグローバル割り当ての超過）のみがクライアントに送信されます。この構成の例を次に示します。

  <FaultRule name="over_quota">
    <!-- This condition catches a QuotaViolation in *any* Quota policy -->
    <Condition>fault.name = "QuotaViolation"</Condition>
    <Step>
      <Name>AM-developer-over-quota-fault</Name>
      <Condition>ratelimit.developer-quota-policy.exceed.count GreaterThan 0</Condition>
    </Step>
    <Step>
      <Name>AM-global-over-quota-fault</Name>
      <Condition>ratelimit.global-quota-policy.exceed.count GreaterThan 0</Condition>
    </Step>
  </FaultRule>
  

  別の例については、ポリシーの障害処理に関するこちらのディスカッションをご覧ください。

• ある種類のポリシーを 1 つ使用している場合に複数のエラーを処理するには、そのポリシーが失敗したときに実行される単独の障害ルールを検討し、想定されるエラーのそれぞれにマップする複数のステップを含めます。これにより、1 つの FaultRule が使用されるため、複数の FaultRule（エラータイプごとに 1 つ）を使用する場合よりも XML が簡素化されます。たとえば、次のように異なる AssignMessage ポリシー ステップを異なる条件で実行するように指定できます。

  <FaultRule name="raise-fault-3">
    <!-- This condition catches *any* error in the Verify-API-Key-1 policy. -->
    <Condition>oauthV2.Verify-API-Key-1.failed = "true"</Condition>
    <!-- This first step always executes, which handles errors you haven't mapped with inner conditions. -->
    <Step>
      <Name>AM-Generic-Key-Fault</Name>
    </Step>
    <Step>
      <Name>AM-API-Key-NotFound</Name>
      <Condition>fault.name = "FailedToResolveAPIKey"</Condition>
    </Step>
    <Step>
      <Name>AM-API-Key-Invalid</Name>
      <Condition>fault.name = "InvalidApiKey"</Condition>
    </Step>
  </FaultRule>
  

  注: このパターンを使用する場合は、常に実行する 1 つのステップを含めることを検討してください（条件を指定しないでください）。その理由は、これにより、ステップが実行され、内側の条件にマップされていないエラーについてメッセージが提供されるためです。この無条件のステップを最初に配置します。こうすることで、後のステップでキャッチされた特定のエラーがレスポンスで優先されるようになります。
• エラーが発生する FaultRule を追加します（クライアント側の <ProxyEndpoint> またはターゲット側の <TargetEndpoint>）。各場所に表示されるポリシーごとに FaultRule を含めます。
• RaiseFault ポリシーを FaultRule と組み合わせて使用する場合は、RaiseFault ポリシーと FaultRule の両方によってデータが返される場合に送信されるレスポンス データを調整します。たとえば、HTTP ステータス コードを設定する RaiseFault ポリシーがある場合、ステータス コードをリセットする FaultRule 内の AssignMessage Step も構成することは避けてください。最悪の場合、デフォルトのステータス コードがクライアント アプリに返されます。

• <DefaultFaultRule> 要素は <FaultRules> 要素を補完し、プロキシが障害状態を処理する際に実行するポリシーをより詳細に制御できるようにします。<DefaultFaultRule> を指定すると、次のいずれかまたは両方に該当する場合に実行されます。

  • 他の FaultRule が実行されていない。この場合の特殊なケースは、<FaultRules> 要素がまったく構成されていない場合です。
  • <DefaultFaultRule> の <AlwaysEnforce> 子要素が true である。

  <DefaultFaultRule> に <Condition> 要素を指定することもできます。これは、リクエストの状態や保留中のエラー メッセージ（特定のヘッダーの有無など）に基づいて実行を除外する場合に役立ちます。

  プロキシが常に実行する必要があるポリシーがある場合は、以前の FaultRule が実行済みかどうかにかかわらず、<AlwaysEnforce> を true に設定した <DefaultFaultRule> を使用します。考えられる 1 つのシナリオは、プロキシ リクエストが原因で障害が発生したかどうか、あるいはその障害が以前に処理されたかどうかに関係なく、すべてのケースでヘッダーをレスポンスに挿入するというケースです。次に、<PostFlow>/<Response> セクションで適切な AssignMessage ポリシーを接続します。また、<AlwaysEnforce> が true に設定されている <DefaultFaultRule> で同じポリシーを接続します。

一元化された再利用可能な障害処理のパターン

Apigee プロキシのエラー処理パターンでは、コードが重複していない一元化された障害処理のパターンを説明しています。

FaultRule の作成

FaultRule を追加するには、ProxyEndpoint または TargetEndpoint の XML 構成を編集する必要があります。Apigee UI を使用して、API プロキシの [Develop] ビューの [Code] ペインでこの編集を行うか、ProxyEndpoint または TargetEndpoint を定義する XML ファイルを編集できます。

Apigee UI で FaultRule を作成する場合は、まず実行するポリシーを作成してから FaultRule 構成に追加します（まだ作成されていないポリシーを参照する FaultRule を保存しようとすると、UI にエラーが表示されます）。

FaultRule へのポリシーの追加

FaultRule には任意のポリシーを追加できますが、AssignMessage ポリシーを使用して、エラー条件に対するカスタム レスポンス メッセージを生成するのが一般的です。AssignMessage を使用することで、ペイロード、HTTP ステータス コード、ヘッダー、理由フレーズなどの要素を含む HTTP レスポンスを構成できます。

注: 通常、FaultRule で使用されるポリシーは、標準のフロー パイプラインでは使用されません。そのため、Apigee UI を使用して FaultRule のポリシーを作成する場合は、UI で [Policies] の横にあるプラス記号（+）を選択してポリシーを追加します。

一般的な AssignMessage ポリシーの構成の例を次に示します。

<AssignMessage name="AM-Invalid-Key">
  <Set>
      <Payload contentType="text/plain">That is an error.</Payload>
      <StatusCode>401</StatusCode>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

<AssignTo> 要素は指定されていないことに注意してください。つまり、ポリシーが接続されている場所に応じて、アンビエント メッセージに割り当てられます。

これで、FaultRule でこのポリシーを使用できるようになりました。以下のように、FaultRule では AssignMessage ポリシーを名前で参照します。

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>AM-Invalid-Key</Name>
      </Step>
      <Condition>fault.name = "InvalidApiKey"</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

上記の構成をデプロイすると、API プロキシは、無効な API キーをアプリが提示するたびに AM-Invalid-Key という AssignMessage ポリシーを実行します。

次の例のように、FaultRule で複数のポリシーを実行できます。

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>AM-Invalid-Key</Name>
      </Step>
      <Step>
        <Name>policy2</Name>
      </Step>
      <Step>
        <Name>policy3</Name>
      </Step>
      <Condition>fault.name = "InvalidApiKey"</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

ポリシーは定義された順序で実行されます。FaultRule では、MessageLogging ポリシー、ExtractVariables ポリシー、AssignMessage ポリシーなど、どのポリシーでも使用できます。以下のどちらかに該当する場合、FaultRule の処理は直ちに停止されます。

• FaultRule に含まれるいずれかのポリシーがエラーになった
• FaultRule に含まれるいずれかのポリシー RaiseFault タイプである

FaultRule から返されるカスタムエラー メッセージの定義

API からの明確なエラー レスポンスを定義することをおすすめします。これにより、一貫性のある有益な情報をクライアントに提供できます。

次の AssignMessage ポリシーの例では、<Payload> タグと <StatusCode> タグを使用して、InvalidApiKey エラーの発生時にクライアントに送り返すカスタムエラー レスポンスを定義しています（前述の FaultRule の例をご覧ください）。

<AssignMessage name="AM-Invalid-Key">
  <Set>
    <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization.
       Contact support at [e-mail].</Payload>
    <StatusCode>401</StatusCode>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

このレスポンスの内容は、次のとおりです。

• エラー メッセージとサポートへの連絡用のメールアドレスが含まれているペイロード。
• レスポンスで返される HTTP ステータス コード。
• 理由フレーズ。エラーの簡単な説明です。

DefaultFaultRule の作成

DefaultFaultRule は、別の FaultRule で明示的に処理されないあらゆるエラーの例外ハンドラとして機能します。すべての FaultRule の条件がエラーと一致しない場合は、DefaultFaultRule がエラーを処理します。デフォルトの障害処理を有効にするには、<DefaultFaultRule> タグを ProxyEndpoint または TargetEndpoint の子要素として追加します。

たとえば、以下の TargetEndpoint 構成には、AM-Return-Generic-Error という名前のポリシーを呼び出す DefaultFaultRule が定義されています。

<TargetEndpoint name="default">
  ...
  <FaultRules>
    ...
  </FaultRules>

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>AM-Return-Generic-Error</Name>
    </Step>
  </DefaultFaultRule>

  <HTTPTargetConnection>
    <URL>https://mytarget.example.net</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

一般に、DefaultFaultRule は、予期しないエラーが発生した場合に汎用のエラー メッセージ、たとえばテクニカル サポートの連絡先情報を含むメッセージなどを返すために使用されます。こうしたデフォルト レスポンスには、デベロッパーにわかりやすい情報を提供すると同時に、システムの改ざんに悪用されかねないバックエンド URL などの情報を開示しないという、2 つの目的があります。

汎用エラーを返すには、たとえば以下のような AssignMessage ポリシーを定義します。

<AssignMessage name="AM-Return-Generic-Error">
  <Set>
    <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: [e-mail].</Payload>
  </Set>
</AssignMessage>

別の FaultRule がすでに実行されている場合でも、すべてのエラーに対して DefaultFaultRule を実行するため、<AlwaysEnforce> 要素を <DefaultFaultRule> タグに含めます。DefaultFaultRule は、常に実行対象の最後の FaultRule です。

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>AM-Return-Generic-Error</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

DefaultFaultRule は、発生したエラーのタイプを他の方法で判別できない場合に使用します。たとえば、判別できないエラーが原因で API プロキシが失敗した場合は、DefaultFaultRule を使用して次の AssignMessage ポリシーを呼び出すことができます。このポリシーは、レスポンスの Unhandled-Fault という名前のヘッダーに fault.name 値を書き込みます。

<AssignMessage name="AM-Set-Fault-Header">
  <Set>
    <Headers>
      <Header name="Unhandled-Fault">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

こうすることで、Debug ツールまたはレスポンスでヘッダーを確認して、エラーの原因を把握できます。

PostClientFlow へのメッセージ ロギングの追加

PostClientFlow は、プロキシがエラー状態になった後に実行される唯一のフローです。このフローには MessageLogging ポリシーのみを接続できます。このポリシーは、クライアントにレスポンスが返された後に実行されます。このフローに MessageLogging ポリシーを接続することは、厳密にはエラー処理ではありませんが、エラーが発生したときに情報をログに記録する目的でこれを使用できます。PostClientFlow はプロキシの成否に関係なく実行されるため、PostClientFlow に MessageLogging ポリシーを含めると、MessageLogging ポリシーは必ず実行されます。

現在のフローにおけるポリシー障害の処理

前出のどの例でも、ProxyEndpoint または TargetEndpoint で FaultRule を使用して、あらゆるポリシーエラーをエラー状態の一部として処理しています。これは、ポリシーの continueOnError 要素のデフォルト値が false であるため、つまりポリシーでエラーが発生した場合に制御がエラー状態に移るためです。エラー状態になった制御を標準のパイプラインに戻すことはできず、通常はなんらかの形のエラー メッセージを呼び出し側アプリに返します。

ただし、ポリシーの continueOnError 要素を true に設定すると、制御が現在のフローにとどまり、エラーが発生したポリシーの後には、パイプラインで次に続くポリシーが実行されます。エラーを現在のフローで処理することの利点は、エラー状態を解消してリクエスト処理を完了できる可能性があることです。

continueOnError 要素が true: に設定された verify-api-key という名前の VerifyAPIKey ポリシーを、次に示します。

<VerifyAPIKey continueOnError="true" name="verify-api-key">
  <DisplayName>Verify API Key</DisplayName>
  <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

API キーが欠落しているか無効である場合、VerifyAPIKey ポリシーは oauthV2.verify-api-key.failed 変数を true に設定しますが、処理は現在のフローで続行されます。

この VerifyAPIKey ポリシーを、ProxyEndpoint の PreFlow ステップの 1 つとして追加します。

<ProxyEndpoint name="default">
  ...
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>verify-api-key</Name>
      </Step>
      <Step>
        <Name>FaultInFlow</Name>
        <Condition>oauthV2.verify-api-key.failed = "true"</Condition>
      </Step>
    </Request>
    <Response/>
  </PreFlow>
</ProxyEndpoint>

PreFlow の直後のステップでは、条件を使用してエラーの有無がテストされています。VerifAPIKey ポリシーでエラーが発生していた場合は、FaultInFlow という名前のポリシーが実行されます。それ以外の場合、FaultInFlow ポリシーはスキップされます。FaultInFlow ポリシーでは、エラーのログ記録、エラー解消の試行、その他のアクションの実行など、さまざまな処理ができます。

RaiseFault ポリシーを使用したエラーのトリガー

フロー中にいつでも RaiseFault ポリシーを使用してエラーをトリガーできます。RaiseFault ポリシーが実行されると、現在のフローが停止され、制御がエラー状態に移ります。

RaiseFault ポリシーの用途の 1 つに、他のポリシーでは検出できない特定条件のテストがあります。前出の例では <Condition> タグが PreFlow <Step> タグに追加されており、条件に合致した場合に FaultInFlow ポリシーが実行されるようになっています。FaultInFlow が RaiseFault ポリシーの場合、制御はエラー状態に移行します。FaultRule のデバッグやテストを目的として RaiseFault ポリシーをフローに挿入することもできます。

RaiseFault ポリシーがエラーをトリガーした場合は、以下の FaultRule と条件を使用して処理できます。

<FaultRule name="raisefault_rule">
  <Step>
    <Name>POLICY-NAME-HERE</Name>
  </Step>
  <Condition>fault.name = "RaiseFault"</Condition>
</FaultRule>

条件でテストしているのは、障害の名前が RaiseFault かどうかです。RaiseFault ポリシーは、常に fault.name の値を RaiseFault に設定します。RaiseFault ポリシー内でカスタム変数を設定することもできます。その場合、Condition 要素内でこれらの変数をテストできます。

ターゲット サーバーからの HTTP エラーコードのカスタム処理

前述の各セクションでは、ポリシーによって生成されたエラーに対する例を示しました。さらに、トランスポート レベルのエラー、つまりターゲット サーバーから返された HTTP エラーに対するカスタム レスポンスも作成できます。HTTP エラーからのレスポンスを制御するには、HTTP レスポンス コードを処理するように TargetEndpoint を構成します。

デフォルトでは、Apigee は 1xx-3xx の範囲内の HTTP レスポンス コードを「成功」として処理し、4xx-5xx の範囲内の HTTP レスポンス コードを「失敗」として処理します。つまり、HTTP レスポンス コード 4xx-5xx を含むバックエンド サービスからのレスポンスでは、エラー状態が自動的に呼び出され、リクエスト元のクライアントにエラー メッセージが直接返されます。

カスタム ハンドラは、あらゆる HTTP レスポンス コードに対して作成できます。たとえば、4xx-5xx の範囲内のすべての HTTP レスポンス コードを「失敗」として処理せずに 5xx の HTTP レスポンス コードのみを「失敗」として処理するか、HTTP レスポンス コード 400 と 500 の場合にカスタムエラー メッセージを返すことができます。

次の例では、success.codes プロパティを使用して、デフォルトの HTTP コードとともに HTTP レスポンス コード 400 と 500 を成功として処理するように TargetEndpoint を構成します。これらのコードを成功として扱うことで、TargetEndpoint がレスポンス メッセージの処理を引き受け、エラー状態は呼び出されません。

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <Properties>
          <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

この例でわかるように、ワイルドカードを使用して success.codes プロパティを値の範囲に設定できます。

success.codes プロパティを設定すると、デフォルト値が上書きされます。したがって、デフォルトの成功コードのリストに HTTP コード 400 を追加する場合は、このプロパティを次のように設定します。

<Property name="success.codes">1xx,2xx,3xx,400</Property>

ただし、HTTP コード 400 のみを成功コードとして扱う場合は、このプロパティを次のように設定します。

<Property name="success.codes">400</Property>

これで HTTP レスポンス コード 400 と 500 のカスタム ハンドラを定義して、リクエスト元のアプリにカスタマイズされたレスポンス メッセージを返すことができます。次の TargetEndpoint は、ReturnError という名前のポリシーを使用して HTTP 400 および 500 レスポンス コードを処理します。

<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request/>
    <Response>
      <Step>
        <Name>ReturnError</Name>
        <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition>
      </Step>
    </Response>
  </PreFlow>

  <HTTPTargetConnection>
    <Properties>
      <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

この TargetEndpoint 構成では、TargetEndpoint が HTTP レスポンス コード 400 または 500 を受け取るたびにレスポンスを処理する ReturnError というポリシーが呼び出されます。

障害の分類

API Services は障害を以下のカテゴリとサブカテゴリに分類します。

カテゴリ	サブカテゴリ	障害名	説明
メッセージング			メッセージ フローの最中に発生した障害（ポリシー障害を除く）
	カスタム障害	{fault_name}	API プロキシが RaiseFault ポリシーを使用して明示的に処理する任意の障害
	レスポンス コード	InternalServerError、NotFound	HTTP エラーコード 5xx、4xx
	ルーティング障害	NoRoutesMatched	リクエストに対する名前付き TargetEndpoint の選択での障害
	分類障害	NotFound	リクエスト URI がどの ProxyEndpoint 構成のどの BasePath とも一致しない（つまり、クライアント アプリのリクエストに含まれている URL に一致する API プロキシがない）ことで発生する障害
トランスポート			HTTP トランスポート レベルエラー
	接続	ConnectionRefused、ConnectionReset、ConnectionTimeout	ネットワークまたはトランスポート レベルの接続を確立している最中に発生したエラー
	リクエストの検証	ContentLengthMissing、HostHeaderMissing	各リクエストのセマンティクス チェック中に発生した障害
	レスポンスの検証		各レスポンスのセマンティクス チェック中に発生した障害
	IO エラー	SSLHandshakeError、ReadTimeout、ReadError、WriteTimeout、WriteError、ChunkError	クライアント エンドポイントまたはターゲット エンドポイントでの読み取り / 書き込みエラー、タイムアウト、TLS / SSL エラー、チャンクエラー
システム			未定義のランタイム エラー
	メモリ	OutOfMemory、GCOverLimit	メモリ関連の障害
	スレッド	RogueTaskTerminated	ランナウェイ タスクの停止などの障害
ポリシー			各ポリシータイプの障害の定義は、ポリシー リファレンスに記載されています。

エラーとともに、エラーの理由に関するテキストの説明が必ず表示されます。システムで障害が発生すると、一連の属性が設定されます。これはトラブルシューティングで役立ちます。障害には以下の情報が含まれます。

• 理由
• ユーザー定義のカスタム属性