障害の処理

API プロキシによるリクエストの処理中にはいろいろなエラーが起こりえます。たとえば、バックエンド サービスとの通信中に API プロキシがネットワークの問題に遭遇したり、アプリが期限の切れた認証情報を提示したり、リクエスト メッセージの形式に誤りがあったりなどすることが考えられます。

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

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

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

動画

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

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

エラーの発生方法

まず、エラーがどのように発生するかについて簡単に説明します。エラーがどのように発生するかを理解しておくと、カスタムエラー処理を実装するさまざまな状況に対応できます。

自動エラー

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

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

これらのエラーの詳細については、このトピックの障害の分類をご覧ください。

カスタムエラー

自動エラーがない状況では、カスタムエラーをスローできます。たとえば、レスポンスに「unavailable」という単語が含まれている場合、または HTTP ステータス コードが 201 より大きい場合などです。これを行うには、Raise Fault ポリシーを API プロキシフローの適切な場所に追加します。

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

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

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

その他の例については、Apigee コミュニティ フォーラムの次の投稿をご覧ください。

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

ここでは、プロキシによってエラーがスローされた場合にどうなるかについて説明します。

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

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

たとえば、API プロキシが ProxyEndpoint リクエスト内に次の順序でポリシーを持っているとします。

  1. Verify API Key
  2. 割り当て
  3. JSON to XML

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

FaultRule の確認

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

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

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

簡単な障害処理の例

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 ヘッダーを設定できる Assign Message などの任意のタイプのポリシーを使用できます。この例には Assign Message が最適です。メッセージ ペイロードを制御したり、さまざまな HTTP ステータス コードを設定したり、さまざまな HTTP 理由句を設定したり、HTTP ヘッダーを追加したりできます。

ポリシーを API プロキシのフローに添付しないでください。プロキシ ハンドルに存在するだけで十分です。管理 UI プロキシ エディタでこれを行うには、[Develop] タブに移動し、ナビゲーション ペインの [Policies] バーにある [+] アイコンをクリックします。

これにより、API プロキシのフローに添付せずにポリシーを作成できます。フローに添付されていないポリシーの場合、[Policies] リストでは「添付解除」アイコンで示されます。これは、上の図の API key message ポリシーの横に表示されています。

Assign Message ポリシーの例を次に示します。

  • JSON メッセージを返します。
  • HTTP ステータス コード(911、明らかに存在しないことを示すステータス コードで、単純に柔軟性があることを示す)を設定します。ステータス コードは、HTTP ヘッダーに表示されます。
  • HTTP 理由句を設定します(デフォルトの「Unauthorized」理由句をこの存在しない API キーエラーに置き換えるため)。理由句は、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>
            <ReasonPhrase>Rejected by API Key Emergency Services</ReasonPhrase>
        </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> セクションに、個別の <FaultRule> セクションが含まれる <FaultRules> XML ブロックを追加します。各 FaultRule は、処理する別のエラーを表します。この簡単な例では、1 つの FaultRule のみを使用して、何で構成されているかを示します。

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 で定義されています。これは重要です。FaultRule を ProxyEndpoint に配置した場合と TargetEndpoint に配置した場合の詳細については、後で説明します。
  • <Name> - 実行するポリシーの名前。前のポリシーの例で示したように、名前は、親要素のポリシーの name 属性から取得されます。
  • <Condition> - Edge によって条件が評価され、条件が true である場合にのみポリシーが実行されます。true に評価される FaultRule が複数ある場合は、true である最初の FaultRule が実行されます(重要: 複数の FaultRule と実行ロジックで説明するように、FaultRule が評価される順序(上から下、下から上)は、TargetEndpoint と ProxyEndpoint とでは異なります)。条件を含めない場合、FaultRule は自動的に true になります。ただし、これはベスト プラクティスではありません。各 FaultRule には独自の条件が必要です。

  • <DefaultFaultRule> - カスタム FaultRule が実行されない場合は、<DefaultFaultRule> が実行され、Edge により生成された暗号のようなデフォルトのメッセージではなく、より汎用的なカスタム メッセージが送信されます。<DefaultFaultRule> にも <Condition> を含めることができますが、ほとんどの場合は含めません。最後の手段としてどのような場合でも実行する必要があるからです。

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

複数の FaultRule と実行ロジック

簡単な障害処理の例では、1 つの FaultRule と条件の簡単な例を使用しました。実際の API プロジェクトでは、あらゆる種類のエラーが発生する可能性があるため、複数の FaultRule と 1 つの DefaultFaultRule を <ProxyEndpoint><TargetEndpoint> の両方に設定する場合が少なくありません。ただし、最終的には、API プロキシがエラー状態になった場合は 1 つの FaultRule のみが実行されます。

このセクションでは、Edge が FaultRule の処理に使用するロジックについて説明します。たとえば、そのロジックが実行する 1 つの FaultRule にどのように到達するか、「内側の」ステップ条件の FaultRule がトリガーされたときにその条件がどのように処理されるか、などについて説明します。FaultRule を <ProxyEndpoint><TargetEndpoint> で定義するタイミングに関するガイダンスも示し、FaultRule と Raise Fault ポリシーの関係について説明します。

FaultRule の実行

簡単に説明すると、ここで示すロジックは、API プロキシがエラー状態になったときに Edge によって使用されます。ProxyEndpoint と TargetEndpoint とでは、FaultRule の評価にわずかな違いがあります。

  1. Edge はエラーが発生した場所に応じて、ProxyEndpoint または TargetEndpoint の FaultRule を評価します。
    • ProxyEndpoint - Edge は構成 XML の一番下<FaultRule> から開始して上に移動し、各 <FaultRule><Condition>(「内側の」<Step> 条件ではなく「外側の」条件)を評価します。
    • TargetEndpoint - Edge は構成 XML の一番上<FaultRule> から開始して下に移動し、各 <FaultRule><Condition>(「内側の」<Step> 条件ではなく「外側の」条件)を評価します。
  2. 条件が true である最初の FaultRule を評価します。FaultRule に条件がない場合はデフォルトで true になります。
    • FaultRule が実行されると、FaultRule 内のすべてのステップが XML 構成の上から下に順番に評価されます。条件のないステップは自動的に評価され(ポリシーが実行され)、「true」に評価される <Condition> を持つステップが実行されます(「false」に評価された条件は実行されません)。
    • FaultRule が実行され、FaultRule 内のステップが(その条件が「false」に評価されるため)実行されない場合、Edge により生成されたデフォルトのエラー メッセージがクライアント アプリに返されます。<DefaultFaultRule> は、Edge によってその 1 つの FaultRule がすでに実行されているため、実行されません

  3. FaultRule が実行されない場合は、<DefaultFaultRule>(存在する場合)が実行されます。

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

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), Edge
         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, Edge looks at this FaultRule
         first. But let's say this FaultRule is FALSE. A policy did not
         throw a FailedToResolveAPIKey error. Edge 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 Edge 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, Edge looks at this FaultRule
         first. Let's say this FaultRule is FALSE.
         A policy did not throw a FailedToResolveAPIKey error.
         Edge 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), Edge
         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 Edge 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

含めるポリシー

ポリシーをステップに配置することによって、FaultRule からポリシーを実行できます。たとえば、Assign Message ポリシーを実行して、クライアント アプリへのレスポンスの書式を設定し、Message Logging ポリシーでメッセージをログに記録できます。ポリシーは、配置された順(XML の上から下)に実行されます。

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

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

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

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

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

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

API プロキシでエラーが発生する場合、エラーは <ProxyEndpoint>(クライアント アプリからのリクエストまたはクライアント アプリへのレスポンス)または <TargetEndpoint>(ターゲット サービスへのリクエストまたはターゲット サービスからの応答)のどちらかで発生します。エラーが発生する場所は、Edge が FaultRule を探す場所です。

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

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

FaultRule と Raise Fault ポリシー

障害ルールと Raise Fault ポリシーは、表面上は障害処理を行う別の方法のように見えます。これは、ある意味では正解です。ただし、これらは連係もします。このセクションでは、2 つの関係について説明します。この関係を理解しておくと、特に両方を使用して障害処理を設計する場合に役立ちます。

以下に簡単に説明します。

  • 障害ルールは、API プロキシがエラー状態になると常に評価されます。
  • Raise Fault ポリシーは、エラーが発生しない場合に API プロキシをエラー状態にする方法です。

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

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

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

Raise Fault ポリシーによってエラーがトリガーされるとどうなるでしょうか。プロキシがエラー状態になるのでしょうか。FaultRule が実行される可能性があるのでしょうか。ここでは、注意が必要な事項を示します。Raise Fault ポリシーがエラー メッセージを返し、FaultRule がトリガーされてエラー メッセージを返す場合、クライアント アプリには何が返されるでしょうか。

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

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

クライアント アプリの受信内容:


    Status Code: 468
    Reason Phrase: Something happened
    Payload: {"Whoa":"Sorry."}
    Header:
      errorNote: woops,gremlins
    

<- FaultRule ポリシーによる設定:


    Status Code: [none]
    Reason Phrase: Something happened
    Payload: {"Whoa":"Sorry."}
    Header:
      errorNote: gremlins
    

<- Raise Fault ポリシーによる設定:


    Status Code: 468
    Reason Phrase: Can't do that
    Payload: {"DOH!":"Try again."}
    Header:
      errorNote: woops
    

条件の作成

条件は、FaultRule の実行の鍵です。FaultRule 条件は、条件フローや Raise Fault 条件などの他の条件を Edge で作成する場合と同じように作成できます。

このセクションの残りをコンテキストで理解できるように、外側の FaultRule 条件と内側のステップ条件を持つ障害ルールのサンプルを次に示します。

    <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 変数の例について説明します。いくつかの例を示します。ポリシーの名前空間については、各ポリシー リファレンス トピックのフロー変数をご覧ください。

  • Raise Fault ポリシー: raisefault.failed(すべての Raise Fault ポリシーで同じ)
  • Verify API Key ポリシー: oauthV2.{policy_name}.failed。例: oauthV2.Verify-API-Key-1.failed
  • Quota ポリシーと Spike Arrest ポリシー: ratelimit.{policy_name}.failed。例: ratelimit.Quota-1.failed

その他の使用可能な変数

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

  • 失敗したポリシーの変数。
  • 障害が発生した時点で存在する HTTP メッセージ変数。たとえば、エラーがレスポンスでスローされた場合、<TargetEndpoint> 内の FaultRule は、HTTP データ response.status.codemessage.contenterror.content などを使用できます。割り当てポリシーが失敗した場合は、変数 ratelimit.{quota_policy_name}.exceed.count を使用できます。トレースツールポリシー リファレンス トピックを使用すると、使用可能な変数や HTTP データがわかります。

詳細情報

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

障害処理は、API プロキシ開発の主要なアーキテクチャ設計タスクです。エラーをいつどのように処理するかを考えたり、エラー メッセージの意味を把握したり、エラー メッセージの形式を設計したりすることに時間をかけることが重要です。それらを考慮した後(あるいは考慮しながら)、以下のベスト プラクティスを使用して障害処理を実装してください。

ここでは、障害処理を設計して作成する際のベスト プラクティスをいくつか示します。

  • FaultRule ごとに、「外側の」<Condition><Step> 要素の兄弟)を指定します。外側の条件がない障害ルールは、自動的に true に評価されます。「内側の」ステップ条件は、FaultRule が true と false のどちらであるかを判断するために使用されません。ステップ条件は、それを含む FaultRule が Edge によって実行された後でのみ評価されます。FaultRule では、一般に、Assign Message(またはその他の)ポリシーを持つ複数のステップを含めて、それぞれにステップ条件を設定します。
  • 同じタイプの複数のポリシー(たとえば、複数の割り当てポリシー)でエラーを処理するには、発生する可能性があるポリシーエラーごとに 1 つの FaultRule を作成します。たとえば、QuotaViolationInvalidMessageWeightStartTimeNotSupported など、割り当てポリシーの発生する可能性があるエラーごとに FaultRule を作成します(ポリシーエラーについては、ポリシーエラー リファレンスをご覧ください。処理が必要な追加のエラーが見つかった場合は、後で戻って FaultRule に追加できます。反復処理しても問題はありませんが、プロキシの再デプロイが必要になります)。このアプローチでは、エラーをスローするポリシーに関係なく同じタイプのエラーをキャッチできるため、FaultRule XML が効率的になります。

    次に、エラーをより細かく制御する必要がある場合は、内側のステップ条件を使用します。たとえば、リクエスト フローで 2 つのポリシーを使用して個々のデベロッパー割り当てとグローバル割り当ての両方を適用する場合は、(どちらか一方で割り当てが超過した場合にスローされる)QuotaViolation エラーでトリガーする「外側の」FaultRule 条件を設定します。次に、ステップ条件を設定して、両方の割り当てポリシーの exceed.count 変数を評価します。関連するエラー(デベロッパー割り当てまたはグローバル割り当ての超過)のみがクライアントに送信されます。この構成の例を次に示します。

        <FaultRule name="over_quota">
        <!-- This condition catches a QuotaViolation in *any* Quota policy -->
          <Condition>(fault.name = "QuotaViolation")</Condition>
          <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>
        </FaultRule>
        

    別の例については、この Apigee コミュニティのスレッドをご覧ください。

  • 1 つのタイプの 1 つのポリシーを使用する場合にエラーを処理するには、そのポリシーが失敗した場合に実行される 1 つの障害ルールを検討し、発生する可能性がある各エラーにマップされる複数のステップを含めます。これにより、複数の FaultRule ではなく 1 つの FaultRule(エラータイプごとに 1 つ)が使用されるため、XML の効率が保持されます。次に例を示します。

        <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>Generic-Key-Fault</Name>
          </Step>
          <Step>
            <Name>Assign-Message-Raise-Fault-1</Name>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
          </Step>
          <Step>
            <Name>Assign-Message-Raise-Fault-2</Name>
            <Condition>(fault.name = "InvalidApiKey")</Condition>
          </Step>
        </FaultRule>
        
  • エラーが発生する場所(クライアント側の <ProxyEndpoint> またはターゲット側の <TargetEndpoint>)に FaultRule を追加します。それぞれの場所に配置されるポリシーごとに FaultRule を含めます。
  • FaultRule では、クライアント アプリにメッセージを返すことができる任意のタイプのポリシーを実行できます。この例には Assign Message が最適です。エラーを追跡する場合は、Message Logging ポリシーでメッセージをログに記録することも検討してください。
  • Raise Fault ポリシーを FaultRule と組み合わせて使用する場合は、Raise Fault ポリシーと FaultRule の両方によってデータが返される場合に送信されるレスポンス データを調整します。たとえば、Raise Fault ポリシーによって HTTP ステータス コードがリセットされた場合は、FaultRule によってステータス コードがリセットされないようにします。最悪の場合、デフォルトのステータス コードがクライアント アプリに返されます。
  • <DefaultFaultRule> の実行:
    • 他の FaultRule が実行されない場合に <DefaultFaultRule> が常に実行されるようにするには、<Condition> を含めないでください。
    • 別の FaultRule が実行された場合でも <DefaultFaultRule> が常に実行されるようにするには、<AlwaysEnforce>true</AlwaysEnforce> 子要素を追加してください。

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

次の Apigee コミュニティの投稿では、コードの重複のない、一元化された障害処理のパターンを説明しています。

https://community.apigee.com/articles/23724/an-error-handling-pattern-for-apigee-proxies.html

FaultRule の作成

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

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

FaultRule へのポリシーの追加

FaultRule には任意のポリシーを追加できますが、Assign Message ポリシーがよく使用されます。Assign Message ポリシーを使用すると、エラー条件に対するカスタム レスポンス メッセージを生成できます。Assign Message を使用することで、ペイロード、HTTP ステータス コード、ヘッダー、理由句などの要素を持つ HTTP レスポンスを構成できます。

以下に、典型的な Assign Message ポリシー構成の例を示します。

    <AssignMessage name="fault_invalidkey">
      <Set>
          <Payload contentType="text/plain">Contact support at support@mycompany.com.</Payload>
          <StatusCode>401</StatusCode>
          <ReasonPhrase>Unauthorized</ReasonPhrase>
      </Set>
      <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    </AssignMessage>
    

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

    <ProxyEndpoint name="default">
      ...
      <FaultRules>
        <FaultRule name="invalid_key_rule">
          <Step>
            <Name>fault_invalidkey</Name>
          </Step>
          <Condition>(fault.name = "InvalidApiKey")</Condition>
        </FaultRule>
      </FaultRules>
    </ProxyEndpoint>
    

上述の構成をデプロイすると、アプリが無効な API キーを提供するたびに、API プロキシにより、fault_invalidkey という Assign Message ポリシーが実行されます。

以下の例のようにすると、1 つの FaultRule で複数のポリシーを実行できます。

    <ProxyEndpoint name="default">
      ...
      <FaultRules>
        <FaultRule name="invalid_key_rule">
          <Step>
            <Name>policy1</Name>
          </Step>
          <Step>
            <Name>policy2</Name>
          </Step>
          <Step>
            <Name>policy3</Name>
          </Step>
          <Condition>(fault.name = "InvalidApiKey")</Condition>
        </FaultRule>
      </FaultRules>
    </ProxyEndpoint>
    

ポリシーは定義されている順序で実行されます。FaultRule では、Message Logging ポリシー、Extract Variables ポリシー、Assign Message ポリシーなど、どのポリシーも使用できます。以下のどちらかに該当すると、FaultRule の処理は直ちに停止されます。

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

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

ベスト プラクティスとして、API からのエラー レスポンスを規定するルールを定義してください。そうすることで、一貫性があって役に立つ情報をクライアントに提供できます。一貫性のあるエラー メッセージの定義の詳細については、RESTful API 設計: エラーについてをご覧ください。

以下の Assign Message ポリシーの例では、<Payload><StatusCode><ReasonPhase>  タグを使用して、クライアントに送り返すカスタムエラー レスポンスを定義しています。

    <AssignMessage name="fault_invalidkey">
      <Set>
        <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization.
           Contact support at support@mycompany.com.</Payload>
        <StatusCode>401</StatusCode>
        <ReasonPhrase>Unauthorized</ReasonPhrase>
      </Set>
      <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    </AssignMessage>
    

このレスポンスには以下が含まれています。

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

DefaultFaultRule の作成

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

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

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

      <DefaultFaultRule name="fault-rule">
        <Step>
          <Name>ReturnGenericError</Name>
        </Step>
      </DefaultFaultRule>
    
      <HTTPTargetConnection>
        <URL>http://mocktarget.apigee.net</URL>
      </HTTPTargetConnection>
    </TargetEndpoint>
    

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

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

    <AssignMessage name="ReturnGenericError">
      <Set>
        <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload>
      </Set>
    </AssignMessage>
    

<DefaultFaultRule> タグに <AlwaysEnforce> 要素を含めると、すでに他の FaultRule の実行中だった場合も含めて、どのエラーに対しても DefaultFaultRule が実行されます。DefaultFaultRule は、常に実行対象のうちの最後の FaultRule です。

      <DefaultFaultRule name="fault-rule">
        <Step>
          <Name>ReturnGenericError</Name>
        </Step>
        <AlwaysEnforce>true</AlwaysEnforce>
      </DefaultFaultRule>
    

DefaultFaultRule は、発生したエラーのタイプを他の方法では判定できない場合に使用します。たとえば、判定できないエラーが原因で API プロキシに障害が発生したとします。その場合は、DefaultFaultRule を使用して、以下に示す AssignMessage ポリシーを呼び出します。このポリシーによって、fault.name 値がレスポンスの DefaultFaultHeader という名前のヘッダーに書き込まれます。

    <AssignMessage async="false" continueOnError="false" enabled="true" name="DefaultFaultRule">
      <DisplayName>DefaultFaultRule</DisplayName>
      <Set>
        <Headers>
          <Header name="DefaultFaultHeader">{fault.name}</Header>
        </Headers>
      </Set>
      <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
      <AssignTo createNew="false" transport="http" type="response"/>
    </AssignMessage>
    

こうすることで、ヘッダーを Edge トレースツールやレスポンスで確認して、エラーの原因を調べられます。

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

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

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

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

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

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

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

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

この Verify API Key ポリシーを、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 ポリシーでは、エラーのログ記録、エラー解消の試行、その他のアクションの実行など、さまざまな処理を行うことができます。

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

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

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

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

    <FaultRule name="raisefault_rule">
      <Step>
        <Name>{policy_name}</Name>
      </Step>
      <Condition>(fault.name = "RaiseFault")</Condition>
    </FaultRule>
    

条件でテストしているのは、障害の名前が RaiseFault かどうかです。

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

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

デフォルトでは、Edge は HTTP レスポンス コード 1xx~3xx を「成功」、4xx~5xx を「失敗」として扱います。つまり、バックエンド サービスからのレスポンスで HTTP レスポンス コード 4xx~5xx が使用されていると必ず、自動でエラー状態が呼び出され、それがリクエスト側クライアントにエラー メッセージを直接返します。

任意の HTTP レスポンス コードに対してカスタム ハンドラを作成できます。たとえば、「失敗」として扱う HTTP レスポンス コードは 4xx~5xx すべてではなく 5xx だけにしたい、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 プロキシによって Raise Fault ポリシーを使用して明示的に処理される任意の障害
レスポンス コード 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 ランナウェイ タスクの停止などの障害
ポリシー 各ポリシータイプの障害については、ポリシー リファレンスに定義されています。

エラーには、障害の理由に関するテキストの説明が必ず付随しています。システムで障害が発生すると、トラブルシューティングの一助となるよう、属性一式が自動で設定されます。障害には以下の情報が含まれます。

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