
概要
エラー条件に応じてカスタム メッセージを生成します。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 ポリシーが実行されると、現在のフローからエラーフローに制御が移り、指定された障害レスポンスがリクエスト元のクライアント アプリに返されます。メッセージ フローがエラーフローに切り替わると、それ以降のポリシー処理は行われません。残りのすべての処理ステップはバイパスされ、障害レスポンスがリクエスト元のアプリに直接返されます。
- 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 |
ポリシーの内部名。 必要に応じて |
なし | 必須 |
continueOnError |
ポリシーが失敗した場合にエラーを返すには、 ポリシーが失敗してもフローの実行を続けるには |
false | 省略可 |
enabled |
ポリシーを適用するには、 ポリシーを無効にするには、 |
true | 省略可 |
async |
この属性はサポートが終了しています。 |
false | 非推奨 |
<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">
属性 | 説明 | 要否 | 型 |
---|---|---|---|
source |
コピー元のオブジェクトを指定します。
|
省略可 | 文字列 |
<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 が指定されている場合、その値は |
省略可 | 文字列 |
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 から入手できます。
関連トピック
障害の処理をご覧ください。