MonetizationLimitsCheck 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

概览

利用 MonetizationLimitsCheck 政策，您可以强制执行获利限制。

具体来说，如果访问获利 API 的应用开发者未购买相关 API 产品的订阅或开发者余额不足，则会触发该政策。在这种情况下，MonetizationLimitsCheck 政策将引发故障并阻止 API 调用。如需了解详情，请参阅强制执行 API 产品开发者订阅。

将 MonetizationLimitsCheck 政策附加到 API 代理后，将填充 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>` 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。
`continueOnError`	false	可选	设置为 `false` 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 `true`，即使在政策失败后，仍可以继续执行流。另请参阅：故障规则仅在错误状态下触发（关于 continueOnError）处理当前流中的故障
`enabled`	true	可选	设置为 `true` 可实施政策。设为 `false` 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。
`async`	false	已弃用	此属性已弃用。

子元素参考

本部分介绍 <MonetizationLimitsCheck> 的子元素。

`<DisplayName>`

除了用于 name 属性之外，还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。

<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> 的特性：

属性	是否必需？	类型	说明
来源	可选	字符串	指定副本的来源对象。如果未指定来源，则系统会将其视为简单消息。例如，如果政策位于请求流中，则来源默认为请求对象。如果该政策位于响应流中，则默认为响应对象。如果省略来源，则可以使用对流变量的绝对引用作为副本的来源。例如，将值指定为 {request.header.user-agent}。如果源变量无法解析或解析为非消息类型，则 <Copy> 会无响应。

属性

是否必需？

类型

说明

来源

可选

字符串

指定副本的来源对象。

如果未指定来源，则系统会将其视为简单消息。例如，如果政策位于请求流中，则来源默认为请求对象。如果该政策位于响应流中，则默认为响应对象。如果省略来源，则可以使用对流变量的绝对引用作为副本的来源。例如，将值指定为 {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`。

MonetizationLimitsCheck 政策 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

概览

<MonetizationLimitsCheck>

语法

示例