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>

エラーコード

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラーメッセージ、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`。

MonetizationLimitsCheck ポリシー

概要

<MonetizationLimitsCheck>

構文

例

子要素のリファレンス

<DisplayName>

構文

例

<FaultResponse>

<AssignVariable>

<Name>

<Value>

<Add>

<Headers>