MonetizationLimitsCheck ポリシー

このページの内容は ApigeeApigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

ポリシー アイコン

概要

MonetizationLimitsCheck ポリシーを使用すると、収益化の上限を適用できます。

具体的には、API にアクセスしているアプリ デベロッパーが、収益化した関連 API プロダクトのサブスクリプションを購入していない場合や、デベロッパーの残高が不足している場合に、ポリシーがトリガーされます。この場合、MonetizationLimitsCheck ポリシーによって障害が発生し、API 呼び出しがブロックされます。詳細については、API プロダクトに対するデベロッパー サブスクリプションの適用をご覧ください。

API プロキシに MonetizationLimitsCheck ポリシーを接続すると、mint フロー変数のリファレンスで説明されているように、mint.limitscheck.*mint.subscription_* フロー変数に値が代入されます。

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

<MonetizationLimitsCheck>

MonetizationLimitsCheck ポリシーを定義します。

デフォルト値 なし
必須かどうか 必須
複合型
親要素 なし
子要素 <DisplayName>
<FaultResponse>
<IgnoreUnresolvedVariables>

次の表は、<MonetizationLimitsCheck> の子要素の概要をまとめたものです。

子要素 必須かどうか 説明
<DisplayName> 省略可 ポリシーのカスタム名。
<FaultResponse> 省略可 リクエスト元のクライアントに返されるレスポンス メッセージを定義します。
<IgnoreUnresolvedVariables> 省略可 フロー内の未解決の変数エラーを無視します。

<MonetizationLimitsCheck> 要素の構文は次のとおりです。

構文

<?xml version="1.0" encoding="UTF-8" standalone="no"?><MonetizationLimitsCheck continueOnError="[true|false]" enabled="[true|false]" name="policy_name">
   <DisplayName>POLICY_DISPLAY_NAME</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>VALUE</IgnoreUnresolvedVariables>
</MonetizationLimitsCheck>

次の例では、デベロッパーが関連する API プロダクトに登録していない場合は、収益化された API へのアクセスがブロックされ、403 ステータスはカスタム メッセージとともに返されます。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MonetizationLimitsCheck continueOnError="false" enabled="true" name="MonetizationLimitsCheck-1">
  <DisplayName>Monetization-Limits-Check-1</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType="text/xml">
        <error>
          <messages>
            <message>Usage has been exceeded ({mint.limitscheck.isRequestBlocked}) or app developer has been suspended</message>
          </messages>
        </error>
      </Payload>
      <StatusCode>403</StatusCode>
    </Set>
  </FaultResponse>
</MonetizationLimitsCheck>

この要素には、すべてのポリシーに共通する次の属性があります。

属性 デフォルト 必須かどうか 説明
name なし 必須

ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。

管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。

continueOnError false 省略可 ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報:
enabled true 省略可 ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。
async   false 非推奨 この属性は非推奨となりました。

子要素のリファレンス

このセクションでは、<MonetizationLimitsCheck> の子要素について説明します。

<DisplayName>

name 属性に加えて、管理 UI プロキシ エディタでポリシーを別の、より自然な響きの名前でラベル付けするために使います。

<DisplayName> 要素はすべてのポリシーに共通です。

デフォルト値 なし
必須かどうか 省略可。<DisplayName> を省略した場合、ポリシーの name 属性の値が使用されます。
文字列
親要素 <PolicyElement>
子要素 なし

<DisplayName> 要素の構文は次のとおりです。

構文

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 要素に属性や子要素はありません。

<FaultResponse>

リクエスト元のクライアントに返されるレスポンス メッセージを定義します。FaultResponse では、RaiseFault ポリシーの <FaultResponse 要素と同じ設定を使用します。

デフォルト値 なし
必須かどうか 省略可
複合型
親要素 <MonetizationLimitsCheck>
子要素 <AssignVariable>
<Add>
<Copy>
<Remove>
<Set>

<AssignVariable>

宛先フロー変数に値を割り当てます。フロー変数が存在しない場合は、AssignVariable によって作成されます。

デフォルト値 なし
必須かどうか 省略可
複合型
親要素 <FaultResponse>
子要素 <Name>
<Value>

たとえば、次のコードを使用して、MonetizationLimitsCheck ポリシーで myFaultVar という名前の変数を設定します。

<FaultResponse>
<AssignVariable>
  <Name>myFaultVar</Name>
  <Value>42</Value>
</AssignVariable>
</FaultResponse>

障害ルールのポリシーで変数にアクセスできます。たとえば、次の AssignMessage ポリシーでは、変数を使用して、障害レスポンスのヘッダーを設定します。

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

MonetizationLimitsCheck ポリシーの <AssignVariable> では、AssignMessage ポリシーの <AssignVariable> 要素と同じ構文を使用します。

<Name>

変数名。詳細については、AssignMessage ポリシーの Name 要素をご覧ください。

デフォルト値 なし
必須かどうか 省略可
文字列
親要素 <AssignVariable>
子要素 なし
<Value>

変数の値。詳細については、AssignMessage ポリシーの Value 要素をご覧ください。

デフォルト値 なし
必須かどうか 省略可
文字列
親要素 <AssignVariable>
子要素 なし

<Add>

HTTP ヘッダーをエラー メッセージに追加します。

デフォルト値 なし
必須かどうか 省略可
複合型
親要素 <FaultResponse>
子要素 <Headers>
<Headers>

追加、設定、コピー、削除する HTTP ヘッダーを指定します。

デフォルト値 なし
必須かどうか 省略可
複合型
親要素 <Add>
<Copy>
<Remove>
<Set>
子要素 なし

例:

ヘッダーの追加

次の例では、request.user.agent フロー変数の値をヘッダーにコピーします。

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>
ヘッダーの設定

次の例では、<AssignTo> 要素で指定されたメッセージ変数に user-agent ヘッダーを設定しています。

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
</Set>
ヘッダーのコピー - 1

次の例では、リクエストから headerA をコピーしています。

<Copy source='request'>
    <Headers>
        <Header name="headerA"/>
    </Headers>
</Copy>
ヘッダーのコピー - 2

次の例では、複数のヘッダーをコピーします。

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

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

ヘッダーの削除 - 1

次の例では、1 つのヘッダーを削除します。

<Remove>
    <Headers>
        <Header name="user-agent"/>
    </Headers>
</Remove>
ヘッダーの削除 - 2

次の例では、複数のヘッダーを削除します。

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

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

<Copy>

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

デフォルト値 なし
必須かどうか 省略可
複合型
親要素 <FaultResponse>
子要素 <Headers>
<StatusCode>

次の表に、<Copy> の属性を示します。

属性 必須かどうか 種類 説明
source 省略可 文字列

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

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

エラー メッセージの HTTP ステータス コードを指定します。source 属性で指定されたオブジェクトの値をコピーまたは設定できます。

デフォルト値 なし
必須かどうか 省略可
複合型
親要素 <Copy>
<Set>
子要素 なし

例:

ステータス コードのコピー
<Copy source='response'>
    <StatusCode>404</StatusCode>
</Copy>
ステータス コードの設定
<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

<Remove>

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

デフォルト値 なし
必須かどうか 省略可
複合型
親要素 <FaultResponse>
子要素 <Headers>

<Set>

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

デフォルト値 なし
必須かどうか 省略可
複合型
親要素 <FaultResponse>
子要素 <Headers>
<Payload>
<StatusCode>
<Payload>

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

デフォルト値 なし
必須かどうか 省略可
文字列
親要素 <Set>
子要素 なし

例:

テキスト ペイロードの設定
<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>
JSON ペイロードの設定 - 1
<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>
JSON ペイロードの設定 - 2
<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

この例では、variablePrefix 属性と variableSuffix 属性に区切り文字を使用して変数を挿入しています。

JSON ペイロードの設定 - 3
<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

この例では、中括弧を使用して変数を挿入します。16.08.17 リリース以降では中括弧を使用できます。

XML ペイロードの設定
<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

この例では、中括弧を使用して変数を挿入します。16.08.17 リリース以降では中括弧を使用できます。

<IgnoreUnresolvedVariables>

未解決の変数を検出したときに処理を停止するかどうかを決定します。

true を設定すると、未解決の変数を無視して処理を続行できます。それ以外の場合は false を設定します。デフォルト値は true です。

<IgnoreUnresolvedVariables>true に設定することは、<MonetizationLimitsCheck>continueOnErrortrue に設定することとは異なります。continueOnErrortrue に設定すると、変数のエラーだけでなく、すべてのエラーが無視されます。

<IgnoreUnresolvedVariables> 要素の構文は次のとおりです。

構文

<IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

次の例では、<IgnoreUnresolvedVariables>false に設定します。

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

エラーコード

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきこと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス 原因
mint.service.subscription_not_found_for_developer 500 このエラーは、デベロッパーに API プロダクトのサブスクリプションがない場合に発生します。
mint.service.wallet_not_found_for_developer 500 このエラーは、プリペイドのデベロッパーが、料金プランで指定された通貨のウォレットを維持せず、収益化対象の API を使用しようとした場合に発生します。
mint.service.developer_usage_exceeds_balance 500 このエラーは、プリペイドのデベロッパーの使用量がウォレットの残高を超えている場合に発生します。
mint.service.wallet_blocked_due_to_inactivity 500 このエラーは、プリペイドのデベロッパーのウォレットに 1 年半以上チャージされず、デベロッパーが API を使用しようとした場合に発生します。

障害変数

ポリシーで実行エラーが発生すると、Apigee によってエラー メッセージが生成されます。これらのエラー メッセージはエラー レスポンスで確認できます。多くの場合、システムによって生成されたエラー メッセージは、製品のコンテキストとは関係ありません。エラーのタイプに基づいてエラー メッセージをカスタマイズして、より有用なメッセージにすることができます。

エラー メッセージをカスタマイズするには、障害ルールまたは RaiseFault ポリシーを使用します。障害ルールと RaiseFault ポリシーの違いについては、FaultRule ポリシーと RaiseFault ポリシーをご覧ください。障害ルールと RaiseFault ポリシーの両方で Condition 要素を使用して条件を確認する必要があります。Apigee では、各ポリシーに固有の障害変数が用意されています。障害変数の値は、ポリシーがランタイム エラーをトリガーするときに設定されます。これらの変数を使用することで、特定のエラー条件を確認し、適切なアクションを実行できます。エラー条件の確認について詳しくは、条件の作成をご覧ください。

変数 説明
fault.name fault.name は、ランタイム エラーの表にある障害のいずれかに一致します。障害名は、障害コードの最後の部分です。 fault.name Matches "UnresolvedVariable"
MonetizationLimitsCheck.POLICY_NAME.failed POLICY_NAME は、障害が発生したポリシーのユーザー指定の名前です。 MonetizationLimitsCheck.monetization-limits-check-1.failed = true
ポリシーエラーの詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

フロー変数

MonetizationLimitsCheck ポリシーの実行時に、事前定義の次のフロー変数が自動的に入力されます。詳細については、mint フロー変数をご覧ください。

フロー変数 説明
mint.limitscheck.is_request_blocked ブロックされたリクエストでは true
mint.limitscheck.is_subscription_found API サブスクリプションが見つかった場合は true
mint.limitscheck.purchased_product_name 購入した API プロダクトの名前。例: MyProduct
mint.limitscheck.status_message ステータス メッセージ。例: limits_check_success
mint.subscription_end_time_ms API プロダクト サブスクリプションの終了時刻。
mint.subscription_start_time_ms API プロダクト サブスクリプションの開始時刻。例: 1618433956209