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

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

简介

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

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

通过具有自定义属性的费率方案,您可以在 API 调用的消息中标识用作计数器的值,该值用于计算交易计数和费用。

支持以下具有自定义属性的费率方案:

  • 具有自定义属性的价目表
  • 具有自定义属性的可调整通知

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

了解自定义属性计算

自定义属性值如何纳入费率方案的交易计数和费用取决于充电模式,如下表所示。

充电模式 自定义属性计算
固定费率和音量频带

custom attribute number * rate = charge to developer

对于固定费率,自定义属性编号就是与该费率相乘的交易次数。对于音量频段,一个频段中的事务数会按自定义属性号递增,而开发者需要为该事务数付费。例如,如果消息中的自定义属性值为 10,则开发者需要支付 10 笔交易的费用,并且 10 笔交易会计入当前频段计数。如果开发者在当前频段中只剩下 6 项事务,则用 6 乘以该频段的比率。其余 4 个频带进入下一个频段,然后与该频段的速率相乘。

在音量频段方案中,如果最后一个音量频段有限制(不是“无限”),并且有交易超过该限制,会发生以下两种情况:

Bundles

由于套装是按群组收费,而不是按交易收费,因此需要进行以下计算:

custom attribute number = amount added to bundle count

例如,如果消息中的自定义特性编号为 10,则软件包中使用的交易次数加上 10。如果开发者当前的软件包中只剩 6 笔交易,则系统会填充该软件包,并且下一个软件包数量会递增 4。针对下一个软件包(如果有)收取的费率。

如果最后一个 app bundle 具有限制(不是“无限制”),并且某笔交易超出了该限制,会发生以下两种情况:

可调整的通知

对于可调整通知,进行以下计算:

custom attribute number = amount added to transaction count

例如,如果消息中的自定义属性编号为 10,则总交易次数加上 10。

费率方案从何处获取自定义属性值

交易记录政策(适用于 API 产品组合)会指示创收功能在什么位置查找自定义属性值的消息。您可以在 API 商品套装的交易记录政策的“自定义属性”部分定义自定义属性。

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

简要流程如下:

  1. 添加 API 产品时定义自定义属性。
  2. 创建一个包含相应商品的 API 软件包。
    在 API 产品套装的交易记录政策中,添加将用于定义费率方案的自定义属性。
  3. 为 API 产品组创建价目表类型或可调整通知的费率方案,并指定自定义评分参数

下图显示了交易记录政策中定义的自定义属性与价目表方案配置之间的关系。具有自定义属性费率方案关系的可调整通知与此类似,但音量频段值不适用。

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

交易记录政策可以在多个位置(例如响应标头、响应正文或响应中的预定义数据流变量)查找自定义属性值。(请求不可用,因为在您收到成功响应之前,事务不是正式的。)以下示例说明了如何在消息中添加带有数值的响应标头。在这两种情况下,我们都会结合使用分配消息政策与变量。

将请求载荷大小添加到响应标头中

每个消息请求中都有一个 client.received.content.length 变量,其中包含请求载荷中的字节数。通过将“分配消息”政策附加到代理端点响应,我们可以生成一个名为 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 的变量中。使用附加到代理端点响应的“分配消息”政策,您可以生成一个名为 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 界面配置包含自定义属性的价目表方案,如以下部分所述。

Edge

要使用 Edge 界面配置包含自定义属性的价目表方案,请执行以下操作:

  1. 添加 API 产品时定义自定义属性。
  2. 创建包含相应商品的 API 商品套装。请参阅创建 API 商品套装
    在 API 产品套装的交易记录政策中,添加将用于定义费率方案的自定义属性。如需了解详情,请参阅本主题中的简介以及创建交易记录政策
  3. 为 API 产品组合创建费率方案,并指定自定义评分参数

有关详情,请参见使用界面配置价目表方案详情

传统 Edge (Private Cloud)

若要使用传统版 Edge 界面创建包含自定义属性方案的价目表,请按以下步骤操作:

  1. 在 API 产品的交易记录政策中,添加将用于定义费率方案的自定义属性。如需了解详情,请参阅本主题中的简介和创建交易记录政策。对要包含在 API 软件包中的每个 API 产品执行此操作。
  2. 按照所需的方式准确配置 API 产品和交易记录政策后,请创建包含相应产品的 API 软件包。请参阅创建 API 软件包
  3. 为 API 软件包创建费率方案,选择具有自定义属性的价目表作为费率方案类型。
  4. 点击价目表链接。系统会打开“价目表”窗口。

  5. 从“自定义属性”下拉菜单中选择一个自定义属性。该菜单会列出交易记录政策中为商品创建的自定义属性。系统会根据每笔交易中所选自定义属性的值向开发者收费。
    (属性值 * 费率 = 向开发者收取的费用)
  6. (可选)设置免费增值方案,如指定价目表方案详细信息中所述。
  7. 按照指定价目表方案详情中的说明设置收费模式。不过请注意,对于“具有自定义属性费率方案的价目表”,费用模式取决于您选择的自定义属性。例如,如果您选择固定费率作为收费模式,系统会根据自定义属性(例如每次事务中传输的字节数)按固定费率向开发者收费(而不是每次事务的固定费率)。如需了解详情,请参阅计算
  8. 点击保存草稿
    请仅在您确定方案最终确定后再发布。如需了解如何设置发布日期和发布方案,请参阅发布费率方案

有关详情,请参见 使用界面指定价目表方案详情

通过界面配置带有自定义属性的可调整通知计划

如下所述,配置带有自定义特性的可调整通知方案。

边缘

要使用 Edge 界面配置包含自定义属性的价目表方案,请执行以下操作:

  1. 添加 API 产品时定义自定义属性。
  2. 创建包含相应商品的 API 商品套装。请参阅创建 API 商品套装
    在 API 产品套装的交易记录政策中,添加将用于定义费率方案的自定义属性。如需了解详情,请参阅本主题中的简介以及创建交易记录政策
  3. 为 API 产品组合创建费率方案,并指定自定义评分参数

如需了解详情,请参阅使用界面配置可调整的通知计划

传统 Edge (Private Cloud)

如需使用传统版 Edge 界面配置包含自定义属性的价目表方案,请执行以下操作:

  1. 在 API 产品的交易记录政策中,添加将用于定义费率方案的自定义属性。如需了解详情,请参阅本主题中的简介和创建交易记录政策。对要包含在 API 软件包中的每个 API 产品执行此操作。
  2. 按照所需的方式准确配置 API 产品和交易记录政策后,请创建包含相应产品的 API 软件包。请参阅创建 API 软件包
  3. 为 API 套餐创建费率方案,选择带自定义属性的可调整通知作为费率方案类型。
  4. 点击详细信息链接。系统随即会打开“可调整通知”窗口。

  5. 自定义属性下拉菜单中选择一个自定义属性。该菜单会列出交易记录政策中为商品创建的自定义属性。开发者的交易总数根据每笔交易中所选自定义属性的值计算。
  6. 汇总基础设置为对交易量进行汇总的时间段。请选择一个介于 1 到 24 个月之间的数字。此值默认为 1 个月。
  7. 点击 Apply and Close
  8. 点击保存草稿
    请仅在您确定方案最终确定后再发布。如需了解如何设置发布日期和发布方案,请参阅发布费率方案

如需了解详情,请参阅 使用界面指定可调整的通知方案详细信息

使用 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