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 に設定します。関連項目:

 false 省略可
enabled

ポリシーを適用するには、true に設定します。

ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。

 true 省略可
async

この属性は非推奨となりました。

 false 非推奨

<DisplayName> 要素

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

<DisplayName>Policy Display Name</DisplayName>
デフォルト

なし

この要素を省略した場合、ポリシーの 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 フロー変数の値をヘッダーにコピーします。

<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> はレスポンスに失敗します。
 省略可 文字列

<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 が指定されている場合、その値は 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

エラー レスポンスの例

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

スキーマ

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

関連トピック

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