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 ポリシーが実行されると、次の事前定義されたフロー変数が使用可能になります。フロー変数の詳細については、変数リファレンスをご覧ください。

エラー リファレンス

このセクションでは、このポリシーによってエラーが発生したときに返される障害コードとエラー メッセージ、Edge によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

ポリシーの実行時に、以下のエラーが発生することがあります。

デプロイエラー

なし。

障害変数

以下の変数は、ランタイム エラーが発生したときに設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

エラー レスポンスの例

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

障害ルールの例

    <FaultRule name="RaiseFault">
        <Step>
            <Name>RF-ThrowError</Name>
            <Condition>(fault.name Matches "RaiseFault") </Condition>
        </Step>
    </FaultRule>
    

スキーマ

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

関連トピック

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