使用自定义属性配置费率方案

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。信息

简介

在某些情况下，您可能需要基于变量或自定义值的交易计数器。例如，您可能需要：

• 根据 API 调用消息中提供的值向开发者收取可变金额。例如，您可能希望根据 API 请求中传输的字节数向应用开发者收费。
• 将多个 API 调用捆绑到单个事务中。

使用具有自定义属性的费率方案，您可以标识 API 调用的消息中充当计数器的值，该值用于计算交易计数和费用。

系统支持以下包含自定义属性的费率方案：

• 包含自定义属性的价目表
• 带有自定义属性的可调节通知

每个费率方案最多可以设置 10 个自定义属性。

了解自定义属性计算

自定义属性值如何计入费率方案的交易次数和扣款金额取决于计费模式，如下表所示。

充电模式	自定义属性计算
统一费率和基于数量区间的费率	custom attribute number * rate = charge to developer 对于固定费率，自定义属性编号将成为交易次数，并与费率相乘。对于“按交易量划分费率区间”类型，系统会按自定义属性数量递增一个区间的交易量，并按该交易量向开发者收费。例如，如果消息中的自定义属性值为 10，则系统会向开发者收取 10 笔交易的费用，并将 10 笔交易添加到当前频段计数。如果开发者当前只剩 6 笔交易，则 6 会乘以该费率档的费率。剩下的 4 个小时会计入下一个费率档，并乘以该费率档的费率。 在按流量分段的方案中，如果最后一个流量分段设有限制（而非“无限”），并且某笔交易超出了该限制，则会发生以下两种情况： 开发者可免费获得超出数量。 在方案周期重置之前，开发者应用将被禁止进一步调用该 API。 如需详细了解套餐方案的重置时间，请参阅何时收取周期性费用并重置套餐方案？。
套装	由于套装按组收费，而不是按交易收费，因此系统会按以下方式进行计算： custom attribute number = amount added to bundle count 例如，如果消息中的自定义属性编号为 10，则系统会将 10 添加到套装中使用的交易数量。如果开发者当前软件包中只剩下 6 笔交易，则该软件包已满，下一个软件包计数会增加 4 个。系统会按下一个套餐的费率（如有）收费。 如果最后一个 bundle 具有限制（不是“不受限制”），并且事务超出该限制，会发生以下两种情况： 开发者可免费获得超出数量。 在方案周期重置之前，开发者应用将被禁止进一步调用该 API。 如需详细了解何时重置方案，请参阅何时收取周期性费用以及何时重置套餐方案？。
可调节的通知	对于可调整的通知，系统会按以下方式进行计算： custom attribute number = amount added to transaction count 例如，如果消息中的自定义属性编号为 10，则系统会将 10 添加到交易总数中。

价格方案从何处获取自定义属性值

事务记录政策（在 API 产品套件中）会告知 Monetize 在消息中查找自定义属性值的位置。您可以在 API 商品套件的交易记录政策的“自定义属性”部分中定义自定义属性。

然后，在创建包含已定义自定义属性的交易记录政策的 API 产品套件后，您可以在费率方案中选择该自定义属性。

总体流程如下：

1. 在添加 API 产品时定义自定义属性。
2. 创建包含该产品的 API 产品套装。
   在 API 产品套件的交易记录政策中，添加将用于定义费率方案的自定义属性。
3. 为 API 产品套装创建费率方案（类型为费率卡或可调整通知），并指定自定义评分参数。

下图显示了在交易记录政策中定义的自定义属性与费率卡方案配置之间的关系。与自定义属性费率方案关系相关的可调整通知类似，但不适用“按流量分段”值。

如何在消息中生成自定义属性值

交易记录政策可以在多个位置（例如响应标头、响应正文或响应中的预定义流变量）查找自定义属性值。（在您收到成功响应之前，交易不会正式生效，因此无法发出该请求。）以下示例展示了如何将响应标头及其数值添加到消息中。在这两种情况下，我们都将“分配消息”政策与变量搭配使用。

向响应标头添加请求载荷大小

在每个消息请求中，都有一个 client.received.content.length 变量，其中包含请求载荷中的字节数。通过将 Assign Message 政策附加到代理端点响应，我们可以生成一个名为 messageSize 的响应标头，其中包含长度值：

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="messageSize">{client.received.content.length}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

向标头添加应用自定义属性值

同样，我们可以生成包含应用自定义属性值的标头。例如，如果您在每个开发者应用中添加一个名为 apprating 的自定义属性，如下所示：

使用“验证 API 密钥”政策（启用此政策是启用创收功能的前提条件）时，此值会存储在名为 verifyapikey.{policy_name}.apprating 的变量中。使用附加到代理端点响应的 AssignMessage 政策，您可以生成一个名为 apprating 的标头，其中包含应用的 apprating 值：

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="apprating">{verifyapikey.Verify-API-Key-1.apprating}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

设置价格方案

除了上述自定义属性设置外，费率方案的设置方式与您通常的设置方式（适用于不含自定义属性的费率方案）相同，但必须遵守以下要求。

使用界面配置包含自定义属性的费率卡方案

如以下部分所述，使用 Edge 界面或传统版 Edge 界面使用自定义属性配置价目表方案。

使用界面配置具有自定义属性的可调通知方案

如下所述，使用自定义属性配置可调整的通知计划。

使用 API 为费率方案指定包含自定义属性的详细信息

执行以下前提步骤：

1. 在 API 产品的交易记录政策中，添加将用于定义费率方案的自定义属性。如需了解详情，请参阅本主题中的简介以及创建交易记录政策。请针对您要添加到 API 软件包中的每个 API 产品执行此操作。
2. 将 API 产品和交易记录政策完全按照您的要求配置后，创建包含该产品的 API 软件包。请参阅创建 API 软件包。

接下来，您需要使用 API 创建费率方案。

在创建费率方案时，您可以使用自定义属性指定费率方案的详细信息。您可以在调用 /organizations/{org_name}/monetization-packages/{package_id}/rate-plans 时在请求正文中的 ratePlanDetails 属性中指定详细信息。在详细信息中，您可以指定一个用于标识自定义属性名称的评分参数值。您还可以指定一个评分参数值，用于汇总指定时间间隔内的自定义属性。

如需查看费率方案详情选项的完整列表，请参阅费率方案详情配置设置。

例如，以下代码会根据名为 messageSize 的自定义属性创建包含自定义属性方案的费率卡（请参阅粗体中的项目）。

$ curl -H "Content-Type:application/json" -X POST -d \
'{
   "name": "Custom attribute-based rate card plan",
   "developer":null,
   "developerCategory":null,
   "currency": {
     "id" : "usd"
     },     
   "description": "Custom attribute-based rate card plan",
   "displayName" : "Custom attribute-based rate card plan",
   "frequencyDuration": "1",
   "frequencyDurationType": "MONTH",
   "earlyTerminationFee": "10",
   "monetizationPackage": {
      "id": "location"
        },
      "organization": {
       "id": "{org_name}"
      },    
   "paymentDueDays": "30",
   "prorate": "false",
   "published": "false",     
   "ratePlanDetails":[
      {
        "currency":{
           "id":"usd"
        },
      "duration":1,
      "durationType":"MONTH",
      "meteringType":"VOLUME",
      "paymentDueDays":"30",
      "ratingParameter":"messageSize",
      "ratingParameterUnit":"MB",
      "organization":{
         "id":"{org_name}"
      },
      "ratePlanRates":[
         {
           "rate":0.15,
           "startUnit":0,
           "type":"RATECARD",
           "endUnit":1000
         },
         {
           "rate":0.1,
           "startUnit":1000,
           "type":"RATECARD",
           "endUnit":null
         }
      ],
      "freemiumUnit":0,
      "freemiumDuration":0,
      "freemiumDurationType":"MONTH",
      "type":"RATECARD",
      "customPaymentTerm":false
      }
    ],
    "freemiumUnit":0,
    "freemiumDuration":0,
    "freemiumDurationType":"MONTH",
    "contractDuration":"1",
    "contractDurationType":"YEAR", 
    "recurringStartUnit": 1,
    "recurringType": "CALENDAR",
    "recurringFee": "10",
    "setUpFee": "10",
    "startDate": "2013-09-15 00:00:00",
    "type": "STANDARD"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location/rate-plans" \
-u email:password

以下代码根据名为 messageSize 的自定义属性（请参阅粗体部分）创建了一个包含自定义属性的可调整通知费率方案。

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "AdjustableNotification",
     "displayName": "Custom attribute-based adjustable notification plan",
     "description": "Custom attribute-based adjustable notification plan",
     "published": "true",  
     "organization": {
      "id": "myorg"
     },
     "startDate": "2016-04-15 00:00:00",
     "type": "STANDARD",
     "monetizationPackage": {
        "id": "p1",
        "name": "test"
     },
     "currency": {
        "id" : "usd",
        "name" : "USD"
     },
     "ratePlanDetails": [
        {
           "type": "USAGE_TARGET",
           "meteringType": "DEV_SPECIFIC",
           "duration": 1,
           "durationType": "MONTH",
           "ratingParameter": "messageSize",
           "ratingParameterUnit": "MB",
           "organization": {
             "id": "myorg"
           },
           "currency": {
             "id": "usd",
             "name": "USD"
           }
        }
     ]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/monetization-packages/p1/rate-plans"  \
-u email:password