RaiseFault ポリシー

概要

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

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

サンプル

FaultResponse を返す

Raise Fault の最も一般的な使用方法は、リクエスト元のアプリにカスタム障害レスポンスを返すことです。404 を返す例を次に示します。

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

FaultResponse ペイロードを返す

より複雑な例として、HTTP ヘッダーと HTTP ステータス コードとともに、カスタム障害レスポンスのペイロードを返す場合があります。次の例では、Edge がバックエンド サービスから受信した HTTP ステータス コードと、発生した障害のタイプを格納したヘッダーを含む XML メッセージが障害レスポンスに代入されます。

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

FaultResponse メッセージにデータを動的に代入するために使用できるすべての変数のリストについては、変数リファレンスをご覧ください。

サービス コールアウトのエラーを処理する


Raise Fault ポリシーについて

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

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

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

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

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

要素リファレンス

要素リファレンスでは、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">
    

次の表に、ポリシーのすべての親要素に共通の属性を記載します。

属性 説明 デフォルト 要否
name

ポリシーの内部名。name 属性の値には、文字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。255 文字を超える値を指定することはできません。

必要に応じて、管理 UI プロキシ エディタで <DisplayName> 要素を使用してポリシーに別のわかりやすい名前でラベルを付けます。

なし 必須
continueOnError

ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される動作です。

ポリシーが失敗してもフロー実行を続行するには、true に設定します。

false 省略可
enabled

ポリシーを適用するには true に設定します。

ポリシーを無効にするには false に設定します。その場合、ポリシーはフローに接続されていているとしても適用されません。

true 省略可
async

この属性は非推奨となりました。

false 非推奨

<DisplayName> 要素

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

<DisplayName>Policy Display Name</DisplayName>
デフォルト:

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます

要否: 省略可
型: 文字列

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

デフォルト:

なし

必須?:

省略可

型:

String

属性

     <Copy source="response">
    
属性 説明 要否
source

コピー元(ソース)のオブジェクトを指定します。

  • source を指定しなかった場合、ソースは単純なメッセージとして扱われます。たとえば、ポリシーがリクエスト フロー内にある場合、ソースはデフォルトではリクエスト オブジェクトです。ポリシーがレスポンス フロー内にある場合、ソースはデフォルトではレスポンス オブジェクトです。source を省略した場合は、フロー変数の絶対参照をコピー元として使用できます。たとえば、値を {request.header.user-agent} として指定します。
  • ソース変数が解決できなかった場合、またはメッセージ以外のタイプに解決された場合、<Copy> は応答に失敗します。
省略可 文字列

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

デフォルト:

false

必須?:

省略可

型:

文字列

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

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

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

デフォルト:

false

必須?:

省略可

型:

文字列

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

デフォルト:

要否:

省略可

型:

String

属性

     <Payload contentType="content_type" variablePrefix="char" variableSuffix="char">
    
属性 説明 要否
contentType

contentType を指定した場合、その値は Content-Type ヘッダーに割り当てられます。

省略可 文字列
variablePrefix JSON ペイロードではデフォルトの "{" 文字を使用できないため、オプションでフロー変数の先頭の区切り文字を指定します。 省略可 Char
variableSuffix JSON ペイロードではデフォルトの "}" 文字を使用できないため、オプションでフロー変数の末尾の区切り文字を指定します。 省略可 Char

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

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

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

デフォルト:

false

必須?:

省略可

型:

ブール値

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

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

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

デフォルト:

false

必須?:

省略可

型:

ブール値

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

デフォルト:

false

必須?:

省略可

型:

ブール値

フロー変数

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

変数 権限 説明
fault.name 文字列 読み取り専用 エラーの障害名を返します。障害名を返せない場合は空の文字列を返します。
fault.type 文字列 読み取り専用 エラーの障害タイプを返します。障害タイプを返せない場合は空の文字列を返します。
fault.category 文字列 読み取り専用 エラーの障害カテゴリを返します。障害カテゴリを返せない場合は空の文字列を返します。

エラー リファレンス

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

ランタイム エラー

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

障害コード HTTP ステータス 原因
steps.raisefault.RaiseFault 500 障害文字列をご覧ください。

デプロイエラー

なし。

障害変数

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

変数 説明
fault.name="fault_name" fault_name は、上記のランタイム エラー表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 fault.name = "RaiseFault"
raisefault.policy_name.failed policy_name は、障害をスローしたポリシーの、ユーザーが指定した名前です。 raisefault.RF-ThrowError.failed = true

エラー レスポンスの例

    {
       "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 に参照用のポリシー スキーマが用意されています。

関連トピック

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