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` 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 `true`，即使在政策失败后，仍可以继续执行流。另请参阅：故障规则仅在错误状态下触发（关于 continueOnError）处理当前流中的故障
`enabled`	true	可选	设置为 `true` 可实施政策。设为 `false` 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。
`async`	否	已弃用	此属性已弃用。

子元素参考

本部分介绍 <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>

错误代码

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 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 政策之间的差异，请参阅 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`	`true`（如果找到 API 订阅）。
`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`。