ポリシーエラーについて知っておくべきこと

このトピックでは、ポリシーエラーの構造と、ポリシーエラーが発生すると設定されるフロー変数の種類について説明します。プロキシの障害処理を設計して実装する場合、ここで提供する情報が不可欠となります。

このトピックでは、Edge での障害処理の基本的な仕組みを理解していること、障害ルールとは何かを理解していることを前提とします。説明が必要な場合は、障害の処理をご覧ください。ここで提供する情報は、ポリシーエラー リファレンスを使用するうえでも役立ちます。

デフォルトのポリシーエラー レスポンスについて

ポリシーがエラーをスローすると、Edge は直ちにエラーフローを開始してエラー メッセージを生成します。システムによって生成されるエラー メッセージは、errorcode と faultstring の 2 つの情報が格納された JSON オブジェクトです。

例:

{
   "fault":{
      "detail":{
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"foo message is not available for ExtractVariable: ParseJsonResponse"
   }
}

このエラー メッセージの各構成要素を以下に簡単に説明します。

errorcode は、[prefix].[error_name] という形式の接頭辞とエラー名から構成されます。上記の例では、「steps.extractvariables」が接頭辞で、SourceMessageNotAvailable がエラー名です。接頭辞はエラーを生成したポリシーの種類を示します。上記の例では、Extract Variables ポリシーによってエラーが生成され、そのエラーの名前が SourceMessageNotAvailable であることがわかります。

faultstring には、エラーの説明が格納されます。通常、障害文字列にはポリシーの名前や未解決の変数の名前、あるいはエラーと関係するなんらかの要素が含まれます。こうした情報が、エラーの原因となった特定の問題を見つける手がかりとなります。たとえば、上記のエラー メッセージでは 「foo」がポリシー内で参照された未解決のメッセージ変数の名前、「ParseJsonResponse」がエラーをトリガーしたポリシーの名前です。

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

ポリシーエラーがトリガーされると、特定のエラーに固有のフロー変数に値が取り込まれます。障害処理では、こうした変数が非常に役立ちます。障害の処理で説明しているように、一般的な手法では、システム生成のポリシーエラーをトラップして後続のアクション（カスタムのエラー レスポンスの作成など）を実行します。たとえば、セキュリティ上の理由により、Edge から返される実際のエラーとステータス コードがクライアントに表示されないようにできます。

fault.name 変数

ポリシーがエラーをスローするときはフロー変数 fault.name を errorcode の error_name の部分に設定します（前のセクションを参照）。この変数を評価して条件付きで障害ルールを実行するのは非常に一般的なことです。

以下に、fault.name の値をテストするサンプル障害ルールを示します。

<faultrule name="VariableOfNonMsgType"<>/faultrule><FaultRule name="Source Message Not Available Fault">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name Matches "SourceMessageNotAvailable") </Condition>
    </Step>
</FaultRule>

ポリシーがエラーをトリガーすると、必ず fault.name がそのエラーの名前に設定されるという点を覚えておいてください。

[prefix].[policy_name].failed 変数

デベロッパーが一般的に確認する変数には fault.name の他に [prefix].[policy_name].failed フラグもあります。ポリシーの実行時に、この変数は true または false のいずれかに設定されます。障害ルールでこの変数をチェックして、値が true に設定されているかどうか、つまりエラーが発生したかどうかを確認する必要があります。ここからは、[prefix].[policy_name].failed フラグをチェックする条件の作成方法を説明します。まず、この変数を正しくチェックするには、次の 2 つの情報を知る必要があります。

  • チェック対象のポリシーの名前。これはポリシーの表示名ではなく、name 属性の値です。この属性は常にポリシー定義の XML に含まれています。
  • チェック対象のポリシーのタイプに固有の接頭辞（以下に、接頭辞を見つける方法を説明します）。

説明のために、別の障害ルールの例を取り上げます。[prefix].[policy_name].failed 変数名を形成する外側の条件に注目してください。この例では、接頭辞が extractvariables で、ポリシー名が ParseJsonResponse です。この例ではこの変数が true に設定されている場合にのみ、障害ルールが実行されます。ヒントとして、障害ルールには複数のステップを含めることができるため、障害ルールを複数のブロックに編成するには、このパターンが役立ちます。

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="Extract Variable Faults">
    <Step>
        <Name>AM-CustomErrorMessage</Name>
        <Condition>(fault.name Matches "SourceMessageNotAvailable") </Condition>
    </Step>
    <Condition>(extractvariables.ParseJsonResponse.failed = true) </Condition>
</FaultRule>

error 変数と message 変数について

error 変数は、プロキシのエラーフローでのみ利用可能です。error 変数からは、エラー メッセージ、ステータス コード、理由句などの有用な情報を入手できます。error 変数の形式は次のパターンになります。

error.[error_component] = [value]

例:

error.message = "request message is not available for ExtractVariable: ParseJsonResponse"

および

error.status.code = "500"

message 変数もエラーフローで利用可能です。この変数は、error 変数と同じような目的で使用できます。message 変数はコンテキストに依存することから、特殊な変数です。リクエスト フローではリクエスト変数のように動作する一方、レスポンス フローではレスポンスの値を取得または設定するために使用できます。詳細については、メッセージ変数のユースケースをご覧ください。

error と message を含む Edge のすべての変数については、変数リファレンスをご覧ください。