營利限制檢查政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

您可以透過 MonetizationLimitsCheck 政策強制執行營利限制。

具體來說，如果存取營利 API 的應用程式開發人員未購買相關 API 產品的訂閱方案，或餘額不足，就會觸發這項政策。在此情況下，MonetizationLimitsCheck 政策會觸發錯誤訊息，並封鎖 API 呼叫。詳情請參閱「強制開發人員訂閱 API 產品」。

將 MonetizationLimitsCheck 政策附加至 API Proxy 時，系統會填入 mint.limitscheck.* 和 mint.subscription_* 流程變數，詳情請參閱 mint 流程變數參考資料。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 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 個半形字元。您可以選擇使用 `<DisplayName>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
`continueOnError`	false	選用	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
`enabled`	是	選用	設為 `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>

設定標頭

以下範例會將 user-agent 標頭設為以 <AssignTo> 元素指定的訊息變數。

<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」的第二個值。如果「h3」只有一個值，系統就不會複製「h3」。

移除標題 - 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」的第二個值。如果「h3」只有一個值，系統就不會移除「h3」。

`<Copy>`

將 source 屬性指定的訊息複製到錯誤訊息中。

預設值	不適用
必填與否	選用
類型	複雜型別
父項元素	`<FaultResponse>`
子元素	`<Headers>` `<StatusCode>`

下表說明 <Copy> 的屬性：

屬性	是否必要	類型	說明
來源	選用	字串	指定副本的來源物件。如未指定 source，系統會將其視為簡單訊息。舉例來說，如果政策位於要求流程中，來源預設為要求物件。如果政策位於回應流程中，預設為 response 物件。如果省略 source，則可以使用流程變數的絕對參照做為副本來源。舉例來說，您可以將值指定為 {request.header.user-agent}。如果無法解析來源變數，或解析為非訊息類型，<Copy> 就無法回應。

屬性

是否必要

類型

說明

來源

選用

字串

指定副本的來源物件。

如未指定 source，系統會將其視為簡單訊息。舉例來說，如果政策位於要求流程中，來源預設為要求物件。如果政策位於回應流程中，預設為 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，Apigee 會忽略所有錯誤，而不只是變數中的錯誤。

<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`	`true` (如果找到 API 訂閱項目)。
`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` - 開發人員的錢包已超過一年未使用。只要加值至少一個單位 (以美元來說就是 $0.01 美元)，即可重新啟用帳戶。 `wallet_not_found` - 開發人員沒有錢包。如果開發人員未執行任何加值作業，就可能發生這種情況。
`mint.subscription_end_time_ms`	API 產品訂閱的結束時間。
`mint.subscription_start_time_ms`	API 產品訂閱的開始時間。例如：`1618433956209`。