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

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

属性 説明 デフォルト 要否
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>

デフォルト:

なし

要否:

省略可

型:

文字列

属性

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

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

  • source が指定されていない場合は、単純なメッセージとして扱われます。たとえば、ポリシーがリクエスト フロー内にある場合、ソースはデフォルトで request オブジェクトになります。ポリシーがレスポンス フロー内にある場合は、デフォルトで response オブジェクトになります。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>

デフォルト:

要否:

省略可

型:

文字列

属性

 <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 文字列 読み取り専用 RaiseFault ポリシーが実行されると、この変数は常に文字列 RaiseFault に設定されます。
fault.type 文字列 読み取り専用 エラーの障害タイプを返します。障害タイプを返せない場合は空の文字列を返します。
fault.category 文字列 読み取り専用 エラーの障害カテゴリを返します。障害カテゴリを返せない場合は空の文字列を返します。

エラー リファレンス

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.

Fault code HTTP status Cause
steps.raisefault.RaiseFault 500 See fault string.

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.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "RaiseFault"
raisefault.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. raisefault.RF-ThrowError.failed = true

Example error response

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

スキーマ

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

関連トピック

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