本頁面由 Cloud Translation API 翻譯而成。

營利限制檢查政策

本頁內容適用於 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>

本範例使用大括號插入變數。自 2016 年 8 月 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>

錯誤代碼

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 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.5 年內未補充，且開發人員嘗試使用 API，就會發生這項錯誤。

錯誤變數

每當政策發生執行錯誤時，Apigee 就會產生錯誤訊息。您可以在錯誤回應中查看這些錯誤訊息。很多時候，系統產生的錯誤訊息在產品情境中可能不相關。您可能會根據錯誤類型自訂錯誤訊息，讓訊息更有意義。

如要自訂錯誤訊息，您可以使用錯誤規則或 RaiseFault 政策。如要瞭解錯誤規則與 RaiseFault 政策的差異，請參閱「FaultRules 與 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`	`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`。