このページの内容は Apigee と Apigee ハイブリッドに該当します。
Apigee Edge のドキュメントを表示する。
概要
エラー条件に応じてカスタム メッセージを生成します。RaiseFault を使用して、特定の条件が発生したときにリクエスト元のアプリに返される障害レスポンスを定義します。
このポリシーは、標準ポリシーであり、任意の環境タイプにデプロイできます。すべてのユーザーがポリシーや環境のタイプを知る必要はありません。ポリシータイプと各環境タイプで使用可能かどうかは、ポリシータイプをご覧ください。
障害の処理に関する一般的な情報については、障害の処理をご覧ください。
サンプル
FaultResponse を返す
RaiseFault の最も一般的な使用方法は、リクエスト元のアプリにカスタム障害レスポンスを返すことです。たとえば、このポリシーはペイロードがない 404
ステータス コードを返します。
<RaiseFault name="404"> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <FaultResponse> <Set> <StatusCode>404</StatusCode> </Set> </FaultResponse> </RaiseFault>
FaultResponse ペイロードを返す
より複雑な例として、HTTP ヘッダーと HTTP ステータス コードとともにカスタム障害レスポンスのペイロードを返す場合があります。次の例では、Apigee がバックエンド サービスから受信した 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> </Set> <Add> <Headers> <Header name="FaultHeader">{fault.name}</Header> </Headers> </Add> </FaultResponse> </RaiseFault>
FaultResponse メッセージを動的に入力するために使用できるすべての変数のリストについては、変数リファレンスをご覧ください。
サービス コールアウト エラーを処理する
RaiseFault ポリシーについて
Apigee では、RaiseFault タイプのポリシーを使用してカスタム例外処理を実行できます。RaiseFault ポリシーは、AssignMessage ポリシーと類似しています。このポリシーを使用すると、エラー条件に応じてカスタム障害レスポンスを生成できます。
RaiseFault ポリシーを使用して、特定のエラー条件が発生したときにリクエスト元のアプリに返される障害レスポンスを定義します。障害レスポンスの構成要素は、HTTP ヘッダー、クエリ パラメータ、メッセージ ペイロードです。アプリのデベロッパーやアプリのエンドユーザーにとって、カスタム障害レスポンスは汎用のエラー メッセージや HTTP レスポンス コードより役に立つことがあります。
RaiseFault ポリシーが実行されると、現在のフローからエラーフローに制御が移り、指定された障害レスポンスがリクエスト元のクライアント アプリに返されます。メッセージ フローがエラーフローに切り替わると、それ以降のポリシー処理は行われません。残りのすべての処理ステップはバイパスされ、障害レスポンスがリクエスト元のアプリに直接返されます。
RaiseFault は ProxyEndpoint または TargetEndpoint で使用できます。通常、Condition を RaiseFault ポリシーに接続します。RaiseFault の実行後、Apigee は通常の障害処理を実行し、FaultRule を評価します。障害ルールが定義されていない場合は、リクエストの処理を終了します。
要素リファレンス
要素リファレンスでは、RaiseFault ポリシーの要素と属性について説明します。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1"> <DisplayName>RaiseFault 1</DisplayName> <FaultResponse> <AssignVariable> <Name/> <Value/> </AssignVariable> <Add> <Headers/> </Add> <Copy source="request"> <Headers/> <StatusCode/> </Copy> <Remove> <Headers/> </Remove> <Set> <Headers/> <Payload/> <StatusCode/> </Set> </FaultResponse> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </RaiseFault>
<RaiseFault> 属性
<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">
次の表に、すべてのポリシーの親要素に共通する属性を示します。
属性 | 説明 | デフォルト | 要否 |
---|---|---|---|
name |
ポリシーの内部名。 管理 UI プロキシ エディタで |
なし | 必須 |
continueOnError |
ポリシーが失敗したときにエラーを返す場合は、 ポリシーが失敗した後もフローの実行を続行する場合は、 |
false | 省略可 |
enabled |
ポリシーを適用するには、 ポリシーを無効にするには、 |
true | 省略可 |
async |
この属性は非推奨となりました。 |
false | 非推奨 |
<DisplayName> 要素
管理 UI プロキシ エディタで name
属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。
<DisplayName>Policy Display Name</DisplayName>
デフォルト |
なし この要素を省略した場合、ポリシーの |
---|---|
要否 | 省略可 |
タイプ | 文字列 |
<IgnoreUnresolvedVariables> 要素
(省略可)フロー内で解決されていない変数エラーを無視します。有効な値: true、falseデフォルトは true
です。
<FaultResponse> 要素
(省略可)リクエスト元のクライアントに返されるレスポンス メッセージを定義します。FaultResponse では AssignMessage ポリシーと同じ設定を使用します。
<FaultResponse><AssignVariable> 要素
宛先フロー変数に値を割り当てます。フロー変数が存在しない場合は、AssignVariable
によって作成されます。
たとえば、次のコードを使用して、RaiseFault ポリシーで myFaultVar
という名前の変数を設定します。
<FaultResponse> <AssignVariable> <Name>myFaultVar</Name> <Value>42</Value> </AssignVariable> ... </FaultResponse>
この変数は、RaiseFault ポリシーのメッセージ テンプレートで参照できます。また、FaultRule に接続されているポリシーは、その変数にアクセスできます。たとえば、次の AssignMessage ポリシーは、RaiseFault で設定された変数を使用して、障害レスポンスにヘッダーを設定します。
<AssignMessage enabled="true" name="Assign-Message-1"> <Add> <Headers> <Header name="newvar">{myFaultVar}</Header> </Headers> </Add> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </AssignMessage>
RaiseFault ポリシーの <AssignVariable>
では、AssignMessage ポリシーの <AssignVariable>
要素と同じ構文を使用します。
<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/> </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>
デフォルト: |
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/> </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 ペイロードではデフォルトの "{" 文字を使用できないため、オプションでフロー変数の先頭の区切り文字を指定します。 | 省略可 | 文字列 |
variableSuffix | JSON ペイロードではデフォルトの "}" 文字を使用できないため、オプションでフロー変数の末尾の区切り文字を指定します。 | 任意 | 文字列 |
<FaultResponse>/<Set>/<StatusCode> 要素
レスポンスにステータス コードを設定します。
<Set source='request'> <StatusCode>404</StatusCode> </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(デフォルト)。
デフォルト: |
false |
プレゼンス: |
省略可 |
型: |
ブール値 |
フロー変数
フロー変数を使用すると、ポリシーとフローの実行中に HTTP ヘッダー、メッセージ コンテンツ、またはフロー コンテキストに基づいた動的な振る舞いを持たせることが可能です。RaiseFault ポリシーが実行されると、事前定義された次のフロー変数が使用可能になります。フロー変数の詳細については、変数リファレンスをご覧ください。
変数 | 型 | 権限 | 説明 |
---|---|---|---|
fault.name | 文字列 | 読み取り専用 | RaiseFault ポリシーが実行されると、この変数は常に文字列 RaiseFault に設定されます。 |
fault.type | 文字列 | 読み取り専用 | エラーの障害タイプを返します。障害タイプを返せない場合は空の文字列を返します。 |
fault.category | 文字列 | 読み取り専用 | エラーの障害カテゴリを返します。障害カテゴリを返せない場合は空の文字列を返します。 |
RaiseFault の使用例
次の例では、Condition を使用して、インバウンド リクエストに zipcode
という queryparam
の存在を適用します。その queryparam
が存在しない場合、フローで RaiseFault によって障害が生成されます。
<Flow name="flow-1"> <Request> <Step> <Name>RF-Error-MissingQueryParam</Name> <Condition>request.queryparam.zipcode = null</Condition> </Step> ... </Request> ... <Condition>(proxy.pathsuffix MatchesPath "/locations") and (request.verb = "GET")</Condition> </Flow>
<RaiseFault name='RF-Error-MissingQueryParam'> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <FaultResponse> <Set> <Payload contentType='application/json'>{ "error" : { "code" : 400.02, "message" : "invalid request. Pass a zipcode queryparam." } } </Payload> <StatusCode>400</StatusCode> </Set> </FaultResponse> </RaiseFault>
エラー リファレンス
このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
障害コード | 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]" } }
スキーマ
各ポリシータイプは XML スキーマ(.xsd
)によって定義されます。参照用のポリシー スキーマは GitHub から入手できます。
関連トピック
障害の処理をご覧ください。