RaiseFault ポリシー

概要

エラー条件に応じてカスタム メッセージを生成します。Raise Fault を使用して、特定の条件が発生したときにリクエスト元のアプリに返される障害レスポンスを定義します。

障害の処理に関する一般的な情報については、障害の処理をご覧ください。

サンプル

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
     <ReasonPhrase>The resource requested was not found</ReasonPhrase>
   </Set>
 </FaultResponse>
</RaiseFault>

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact support@company.com</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
     <ReasonPhrase>Server error</ReasonPhrase>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

Raise Fault ポリシーについて

Apigee Edge では、Raise Fault タイプのポリシーを使用してカスタム例外処理を実行できます。Raise Fault ポリシーは Assign Message ポリシーのバリエーションであり、エラー条件に応じてカスタム障害レスポンスを生成できます。

Raise Fault ポリシーを使用して、特定のエラー条件が発生したときにリクエスト元のアプリに返される障害レスポンスを定義します。障害レスポンスの構成要素は、HTTP ヘッダー、クエリ パラメータ、メッセージ ペイロードです。アプリのデベロッパーやアプリのエンドユーザーにとって、カスタム障害レスポンスは汎用のエラー メッセージや HTTP レスポンス コードより役に立つことがあります。

Raise Fault ポリシーが実行されると、現在のフローからエラーフローに制御が移り、指定された障害レスポンスがリクエスト元のクライアント アプリに返されます。メッセージ フローがエラーフローに切り替わると、それ以降のポリシー処理は行われません。残りのすべての処理ステップはバイパスされ、障害レスポンスがリクエスト元のアプリに直接返されます。

• ProxyEndpoint / TargetEndpoint フローで使用します。単一の条件または条件のセットに応じて障害をトリガーします。障害から特定の障害ルールをトリガーできます。障害ルールが定義されていない場合は、プロキシの処理を終了します。
• 障害の処理中にエラーを検出する場合に、障害ルールで使用します。たとえば、障害ハンドラ自体がエラーを引き起こす可能性があるため、そうしたエラーを RaiseFault によって通知できます。

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

要素リファレンス

要素リファレンスでは、Raise Fault ポリシーの要素と属性について説明します。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">
    <DisplayName>Raise Fault 1</DisplayName>
    <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
            <ReasonPhrase/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

<RaiseFault> 属性

<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">

次の表は、すべてのポリシーの親要素に共通の属性を示したものです。

<DisplayName> 要素

name 属性に加えて、管理 UI プロキシ エディタでポリシーを別の自然言語名でラベル付けするために使います。

<DisplayName>Policy Display Name</DisplayName>

<IgnoreUnresolvedVariables> 要素

（オプション）フロー内の未解決の変数エラーを無視します。有効な値は true または false です。デフォルトは true です。

<FaultResponse> 要素

（省略可）リクエスト元のクライアントに返されるレスポンス メッセージを定義します。FaultResponse では AssignMessage ポリシーと同じ設定を使用します（Apigee Edge for Private Cloud では使用できない）。

<FaultResponse><AssignVariable> 要素

宛先フロー変数に値を割り当てます。フロー変数が存在しない場合は、AssignVariable によって作成されます。

たとえば、次のコードを使用して、Raise Fault ポリシーで、myFaultVar という名前の変数を設定します。

<FaultResponse>
  <AssignVariable>
    <Name>myFaultVar</Name>
    <Value>42</Value>
  </AssignVariable>
</FaultResponse>

障害ルールのポリシーで変数にアクセスできます。たとえば、次の Assign Message ポリシーでは、変数を使用して、障害レスポンスのヘッダーを設定します。

<AssignMessage enabled="true" name="Assign-Message-1">
  <Add>
    <Headers>
      <Header name="newvar">{myFaultVar}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Raise Fault ポリシーの <AssignVariable> では、AssignMessage ポリシーの <AssignVariable> 要素と同じ構文を使用します。この機能は現在、Apigee Edge for Private Cloud では使用できません。

<FaultResponse><Add> / <Headers> 要素

HTTP ヘッダーをエラー メッセージに追加します。空のヘッダー <Add><Headers/></Add> ではヘッダーが追加されません。この例では、request.user.agent フロー変数の値をヘッダーにコピーします。

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

<FaultResponse><Copy> 要素

source 属性で指定されたメッセージからエラー メッセージに情報をコピーします。

    <Copy source="request">
        <Headers/>
        <StatusCode/>
        <ReasonPhrase/>
    </Copy>

属性

 <Copy source="response">

<FaultResponse><Copy> / <Headers> 要素

指定された HTTP ヘッダーをソースからエラー メッセージにコピーします。すべてのヘッダーをコピーするには、<Copy><Headers/></Copy>. を指定します。

<Copy source='request'>
    <Headers>
        <Header name="headerName"/>
    </Headers>
</Copy>

同じ名前のヘッダーが複数ある場合は、次の構文を使用します。

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

この例では、「h1」、「h2」、および「h3」の 2 番目の値がコピーされます。"h3" の値が 1 つしかない場合はコピーされません。

<FaultResponse><Copy> / <StatusCode> 要素

source 属性で指定されたオブジェクトからエラー メッセージにコピーされる HTTP ステータス コードです。

<Copy source='response'>
    <StatusCode>404</StatusCode>
</Copy>

<FaultResponse><Copy> / <ReasonPhrase> 要素

source 属性で指定されたオブジェクトからエラー メッセージにコピーされる理由フレーズです。

<Copy source='response'>
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</Copy>

<FaultResponse><Remove> / <Headers> 要素

指定された HTTP ヘッダーをエラー メッセージから削除します。すべてのヘッダーを削除するには、<Remove><Headers/></Remove> を指定します。この例では、メッセージから user-agent ヘッダーを削除します。

<Remove>
    <Headers>
        <Header name="user-agent"/>
    </Headers>
</Remove>

同じ名前のヘッダーが複数ある場合は、次の構文を使用します。

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

この例では、"h1"、"h2"、および "h3" の 2 番目の値が削除されます。"h3" の値が 1 つしかない場合は削除されません。

<FaultResponse><Set> 要素

エラー メッセージに情報を設定します。

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
        <ReasonPhrase/>
    </Set>

<FaultResponse> / <Set> / <Headers> 要素

エラー メッセージの HTTP ヘッダーを設定または上書きします。空のヘッダー <Set><Headers/></Set> ではヘッダーが設定されません。この例では、user-agent ヘッダーを <AssignTo> 要素で指定されたメッセージ変数に設定します。

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
</Set>

<FaultResponse> / <Set> / <Payload> 要素

エラー メッセージのペイロードを設定します。

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

JSON ペイロードは次のように設定します。

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

JSON ペイロードでは、次の例に示すように、区切り文字付きの variablePrefix 属性と variableSuffix 属性を使用して変数を挿入できます。

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

Cloud リリース 16.08.17 以降では、中かっこも変数の挿入に使用できます。

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

XML の混合ペイロードは次のように設定します。

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

属性

 <Payload contentType="content_type" variablePrefix="char" variableSuffix="char">

<FaultResponse> / <Set> / <StatusCode> 要素

レスポンスのステータス コードを設定します。

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

<FaultResponse> / <Set> / <ReasonPhrase> 要素

レスポンスの理由フレーズを設定します。

<Set source='request'>
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</Set>

<ShortFaultReason> 要素

レスポンスに障害の短い理由を表示するように指定します。

<ShortFaultReason>true|false</ShortFaultReason>

デフォルトでは、ポリシーのレスポンス内の障害の理由が次のようになります。

"fault":{"faultstring":"Raising fault. Fault name : Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

メッセージを読みやすくするために、<ShortFaultReason> 要素を true に設定して、faultstring をポリシー名のみに短縮します。

"fault":{"faultstring":"Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

有効な値: true/false(default)。

フロー変数

フロー変数を使用すると、ポリシーとフローの実行中に HTTP ヘッダー、メッセージ コンテンツ、またはフロー コンテキストに基づいた動的な振る舞いを持たせることが可能です。Raise Fault ポリシーが実行されると、次の事前定義されたフロー変数が使用可能になります。フロー変数の詳細については、変数リファレンスをご覧ください。

エラー リファレンス

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

{
   "fault":{
      "detail":{
         "errorcode":"steps.raisefault.RaiseFault"
      },
      "faultstring":"Raising fault. Fault name: [name]"
   }
}

スキーマ

各ポリシータイプは XML スキーマ（.xsd）によって定義されます。参照用のポリシー スキーマは GitHub から入手できます。

関連トピック

障害の処理をご覧ください。