RaiseFault ポリシー

このページは 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`	ポリシーの内部名。`name` 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。	なし	必須
`continueOnError`	ポリシーが失敗したときにエラーを返す場合は、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。関連項目: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理	false	省略可
`enabled`	ポリシーを適用するには、`true` に設定します。ポリシーを無効にするには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。	true	省略可
`async`	この属性は非推奨となりました。	false	非推奨

<DisplayName> 要素

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

<DisplayName>Policy Display Name</DisplayName>

デフォルト

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

なし

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

要否省略可

タイプ文字列

<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 フロー変数の値をヘッダーにコピーします。

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

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

デフォルト:	なし
プレゼンス:	省略可
型:	文字列

<FaultResponse><Copy> 要素

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

    <Copy source="request">
        <Headers/>
        <StatusCode/>
    </Copy>

デフォルト:	なし
プレゼンス:	省略可
型:	文字列

属性

 <Copy source="response">

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

属性

説明

要否

型

ソース

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

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><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> のサブ要素では、メッセージテンプレートという動的文字列置換機能がサポートされます。

    <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 が指定されている場合、その値は `Content-Type` ヘッダーに割り当てられます。	省略可	文字列
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 は次のようになります。

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

エラーレスポンスの例

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

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

スキーマ

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

RaiseFault ポリシー

概要

サンプル

FaultResponse を返す

FaultResponse ペイロードを返す

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

RaiseFault ポリシーについて

要素リファレンス

<RaiseFault> 属性

<DisplayName> 要素

<IgnoreUnresolvedVariables> 要素

<FaultResponse> 要素

<FaultResponse><AssignVariable> 要素

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

<FaultResponse><Copy> 要素

属性

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

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

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

<FaultResponse><Set> 要素

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

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

属性

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

<ShortFaultReason> 要素

フロー変数

RaiseFault の使用例

エラー リファレンス

ランタイム エラー

デプロイエラー

障害変数

エラー レスポンスの例

スキーマ

関連トピック

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

エラーリファレンス

ランタイムエラー

エラーレスポンスの例