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

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

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

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

このトピックは、Apigee の障害処理の仕組みを理解しており、障害ルールの内容を把握していることを前提としています。確認が必要な場合は、障害の処理をご覧ください。ここで提供する情報は、ポリシーエラー リファレンスを使用するうえでも役立ちます。

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

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

次に例を示します。

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

このエラー メッセージを簡単に説明します。

errorcode は prefix と error name で構成され、[prefix].[error_name] となります。上記の例では、steps.extractvariables が接頭辞、SourceMessageNotAvailable がエラー名です。接頭辞は、エラーを生成したポリシーの種類を示します。上記の例では、ExtractVariables ポリシーによってエラーが生成され、エラーの名前が SourceMessageNotAvailable であることがわかります。

faultstring にはエラーの説明が含まれます。障害文字列には通常、ポリシーの名前、未解決の変数の名前、エラーを招いたすべての要因など、エラーの原因を特定する手がかりとなる情報が含まれています。たとえば、上記のエラー メッセージでは、mymessage がポリシーで参照される未解決のメッセージ変数の名前、ParseJsonResponse がポリシーをトリガーしたポリシーの名前です。

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

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

fault.name 変数

ポリシーがエラーをスローするときに、上記のようにフロー変数 fault.name がエラーコードの 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_COMPONENT = VALUE

次に例を示します。

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

および

error.status.code = "500"

message 変数はエラーフローでも使用可能であり、error 変数と同様の目的に使用できます。メッセージ変数はコンテキストに依存する特殊な変数です。リクエスト フローではリクエスト変数のように動作し、レスポンス フローではレスポンスの値を取得または設定するために使用できます。

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