RaiseFault ポリシー

概要

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

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

サンプル

FaultResponse を返す

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

<RaiseFault name=">;4<04"
 IgnoreUnresolve>dVar<iablestrue/IgnoreUnresolve>dV<ariables
 Fau>ltRe<spo>nse
  < Set
     >Sta<tusCode404/>Status<Code
     Re>asonPhraseThe resource requested was< not found/Re>ason<Phra>se<
   /Set
 /Fau>l<tResponse
/>RaiseFault

FaultResponse ペイロードを返す

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

<RaiseFault name="ExceptionHan>dl<er"
 IgnoreUnresolve>dVar<iablestrue/IgnoreUnresolve>dV<ariables
 Fau>ltRe<spo>nse
  < Set
     Payload contentType=>"te<xt/x>ml"
       rootPlease contact< supp>ort@co<mpany.co>m/root<
     /Pay>load
     StatusCode{r<esponse.sta>tus.co<de}/StatusCo>de
     Reas<onPhraseServe>r er<ror/>Reas<onP>hrase
<   /Set>
   Add
<     Headers
       Heade>r name="<;FaultH>eader&<quot;{fa>ult.<name>}/<Header
     /H>e<aders
   /A>dd
 /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&quo>t<; standalone="yes"?
RaiseFault async="false" continueOnError=&qu>ot;fa<lse" e>nabled="<true" n>ame=&<quot;Raise-Fa>ult-1&quo<t;
    Display>NameRaise F<ault >1/DisplayNa<me
   > FaultRes<ponse
        A>ssignVari<abl>e
          N<ame/
   >       Va<lue/>
        </AssignVariable
     >   Add
      <      He>aders/
      <  /Add
    >    Copy sour<ce="requ>est"<
    >        H<eaders>/
           < StatusC>ode/
    <       > ReasonPh<ras>e/
        /C<opy
    >    Remove
  <        >  Headers/
  <      /Remove>
        Set
<           > Headers/<
   >     <    Payload/
 >     <      ReasonPhrase/
     >    <   StatusCode/
        /Se>t<
    /Fault>Response
    IgnoreUnresolvedVariablestrue/IgnoreUnresolvedVariables
/RaiseFault

<RaiseFault> 属性

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

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

属性	説明	デフォルト	要否
`name`	ポリシーの内部名。`name` 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。	なし	必須
`continueOnError`	ポリシーが失敗した場合にエラーを返すには、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。	false	省略可
`enabled`	ポリシーを適用するには、`true` に設定します。ポリシーを無効にするには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。	true	省略可
`async`	この属性は非推奨となりました。	false	非推奨

<DisplayName> 要素

管理 UI プロキシエディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>

デフォルト

デフォルト	なしこの要素を省略した場合、ポリシーの `name` 属性の値が使用されます。
要否	省略可
タイプ	文字列

なし

この要素を省略した場合、ポリシーの 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="As>sig<n-M>essag<e-1&quo>t;
  Ad<d
    Headers
      >Header name=<"n>ewvar<"{m>yFa<ultV>ar}</Header
    /Headers
  /A>dd
  <IgnoreUnresolvedVariablesf>als<e/IgnoreUnresolvedVariables
  AssignTo createNew="false>&<quot; transpor>t="http" type="response"/
/AssignMessage

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

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

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

<Header> 要素は、メッセージテンプレートと呼ばれる動的文字列置換機能をサポートしています。

<Add>
    <Headers>
        <Header name="user-a>gent"{request.u<ser.age>nt}/H<eader
  > < /He>aders
/Add

デフォルト:	なし
要否:	省略可
型:	文字列

<FaultResponse><Copy> 要素

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

    <Copy source="req>uest"<;
      >  Headers</
        S>tatusCode</
        Rea>sonPh<rase/>
    /Copy

デフォルト:	なし
要否:	省略可
型:	文字列

属性

 <Copy source="resp>onse"

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

属性

説明

要否

型

source

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

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

省略可

文字列

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

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

<Copy source='requ>est&#<39;
   > Headers
<        Header name=">;head<erName&q>u<ot;/
>    /Headers
/Copy

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

<Copy source='requ>est&#<39;
   > Header<s
      Header na>me=&quo<t;h1"/
     > Header< name="h2">;/
  <    Head>e<r nam>e="h3.2"/
    /Headers
/Copy

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

デフォルト:	なし
要否:	省略可
型:	文字列

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

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

<Copy source='respo>nse&#<39;
    St>atu<sCode404/St>a<tusCo>de
/Copy

デフォルト:	false
要否:	省略可
型:	文字列

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

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

<Copy source='respo>nse&#<39;
    Reas>onPhraseThe resource requested was no<t found./Reas>o<nPhra>se
/Copy

デフォルト:	false
要否:	省略可
型:	文字列

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

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

<Remove>
    <Headers>
        <Header name="user-ag>ent&q<uot;/
  > < /Heade>rs
/Remove

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

<Remove>
    <Headers>
      <Header name=">;h1&quo<t;/
      Header >name=&q<uot;h2"/
     > Head<er name=>&<quot;h3>.2"/
    /Headers
/Remove

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

デフォルト:	なし
要否:	省略可
型:	文字列

<FaultResponse><Set> 要素

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

<Set> のサブ要素では、メッセージテンプレートと呼ばれる動的な文字列置換機能がサポートされます。

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

デフォルト:	なし
要否:	省略可
型:	なし

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

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

<Set>
    <Headers>
        <Header name="user-a>gent"{request.header.u<ser-age>nt}/H<eader
  > < /He>aders
/Set

デフォルト:	なし
要否:	省略可
型:	文字列

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

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

<Set>
    <Payload contentType="text/p>lain&quo<t;test12>3<4/Pa>yload
/Set

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

<Set>
    <Payload contentType="application/>json"
        {"name":"<;foo&quo>t<;, &>quot;type":"bar"}
    /Payload
/Set

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

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

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

<Set>
    <Payload contentType="application/>json"
        {"name":"foo", <"ty>p<e&qu>ot;:"{variable_name}"}
    /Payload
/Set

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

<Set>
    <Payload contentType="text>/xml"<;
  >      root
<  >      <  e>1sunday/e1
<  >      <  e>2funday/e2
<  >      <  e>3{var<1}/e3
  > < /Pa>yload
/Set

デフォルト:
要否:	省略可
型:	文字列

属性

 <Payload contentType="content_type" variablePrefix="char" v>ariableSuffix="char"

属性	説明	要否	型
contentType	contentType が指定されている場合、その値は `Content-Type` ヘッダーに割り当てられます。	省略可	文字列
variablePrefix	JSON ペイロードではデフォルトの "{" 文字を使用できないため、オプションでフロー変数の先頭の区切り文字を指定します。	省略可	Char
variableSuffix	JSON ペイロードではデフォルトの "}" 文字を使用できないため、オプションでフロー変数の末尾の区切り文字を指定します。	省略可	Char

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

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

<Set source='requ>est&#<39;
    St>atu<sCode404/St>a<tusC>ode
/Set

デフォルト:	false
要否:	省略可
型:	ブール値

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

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

<Set source='requ>est&#<39;
    Reas>onPhraseThe resource requested was no<t found./Reas>o<nPhr>ase
/Set

デフォルト:	false
要否:	省略可
型:	ブール値

<ShortFaultReason> 要素

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

<ShortFaultReason>true|false</ShortFaultReason>

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

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

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

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

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

デフォルト:	false
要否:	省略可
型:	ブール値

フロー変数

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

変数	型	権限	説明
fault.name	文字列	読み取り専用	RaiseFault ポリシーが実行されると、この変数は常に文字列 `RaiseFault` に設定されます。
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`

エラーレスポンスの例

注: ベストプラクティスとして、エラー処理でエラーレスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストは変更される可能性があるため、依存しないでください。

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

スキーマ

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

RaiseFault ポリシー

概要

サンプル

FaultResponse を返す

FaultResponse ペイロードを返す

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

Raise Fault ポリシーについて

要素リファレンス

<RaiseFault> 属性

<DisplayName> 要素

<IgnoreUnresolvedVariables> 要素

<FaultResponse> 要素

<FaultResponse><AssignVariable> 要素

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

<FaultResponse><Copy> 要素

属性

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

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

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

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

<FaultResponse><Set> 要素

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

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

属性

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

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

<ShortFaultReason> 要素

フロー変数

エラー リファレンス

ランタイム エラー

デプロイエラー

障害変数

エラー レスポンスの例

スキーマ

関連トピック

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

エラーリファレンス

ランタイムエラー

エラーレスポンスの例