MonetizationLimitsCheck ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

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` に設定します。関連情報: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理
`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> はレスポンスに失敗します。

属性

必須かどうか

種類

説明

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> の continueOnError を true に設定することとは異なります。continueOnError を true に設定すると、変数のエラーだけでなく、すべてのエラーが無視されます。

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

構文

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

例

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

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

エラーコード

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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
`mint.service.subscription_not_found_for_developer`	`500`	This error occurs when a developer does not have a subscription to the API Product.
`mint.service.wallet_not_found_for_developer`	`500`	This error occurs when a prepaid developer attempts to consume a monetized API without maintaining a wallet for the currency specified in rate plan.
`mint.service.developer_usage_exceeds_balance`	`500`	This error occurs when a prepaid developer's usage exceeds the wallet balance.
`mint.service.wallet_blocked_due_to_inactivity`	`500`	This error occurs when a prepaid developer's wallet is not topped up in over 1.5 years and the developer attempts to consume an API.

Fault variables

Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.

To customize the error messages, you can use either fault rules or the RaiseFault policy. For information about differences between fault rules and the RaiseFault policy, see FaultRules vs. the RaiseFault policy. You must check for conditions using the Condition element in both the fault rules and the RaiseFault policy. Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors. By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error conditions, see Building conditions.

Variables	Where	Example
`fault.name`	The `fault.name` can match to any of the faults listed in the Runtime errors table. The fault name is the last part of the fault code.	`fault.name Matches "UnresolvedVariable"`
`MonetizationLimitsCheck.POLICY_NAME.failed`	`POLICY_NAME` is the user-specified name of the policy that threw the fault.	`MonetizationLimitsCheck.monetization-limits-check-1.failed = true`

For more information about policy errors, see What you need to know about policy errors

フロー変数

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` - 上限チェックが成功しました。 `apiproduct_name_and_developer_email_not_available` - 上限チェックを行うために API デベロッパーまたは API プロダクト名を特定できません。 `apiproduct_name_not_available` - 上限チェックを行うために API プロダクト名を特定できません。 `developer_email_not_available` - 上限チェックを行うために API デベロッパーのメールアドレスを特定できません。 `developer_usage_exceeds_balance` - 前払いデベロッパー残高が少なすぎます。 `rateplan_not_available` - API プロダクトに料金プランが設定されていません（これはエラーではありません）。 `subscription_not_available` - アプリを所有する API デベロッパーがサブスクリプションを保有していません。 `wallet_disabled_due_to_inactivity` - デベロッパーが 1 年以上ウォレットを使用していません。少なくとも 1 単位（米ドルの場合は $0.01）チャージすると、ウォレットは再び有効になります。 `wallet_not_found` - デベロッパーがウォレットを所有していません。これは、そのデベロッパーのためにチャージが実行されていない場合に発生することがあります。
`mint.subscription_end_time_ms`	API プロダクトサブスクリプションの終了時刻。
`mint.subscription_start_time_ms`	API プロダクトサブスクリプションの開始時刻。例: `1618433956209`。

MonetizationLimitsCheck ポリシー コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要

<MonetizationLimitsCheck>

構文

例

子要素のリファレンス

<DisplayName>

構文

例

<FaultResponse>

<AssignVariable>

<Name>

<Value>

<Add>

<Headers>