使用自訂屬性設定費率方案

您正在查看 Apigee Edge 說明文件。
參閱 Apigee X說明文件。 資訊

簡介

在某些情況下，您可能需要根據變數或自訂值建立交易計數器。例如：

• 根據 API 呼叫訊息中提供的值，向開發人員收取可變金額。舉例來說，您可能想根據 API 要求中傳輸的位元組數，向應用程式開發人員收費。
• 將多個 API 呼叫合併為單一交易。

使用含有自訂屬性的費率方案，您可以在 API 呼叫的訊息中識別值，做為計數器，用於計算交易次數和費用。

系統支援下列含有自訂屬性的費率方案：

• 含有自訂屬性的價目表
• 使用自訂屬性調整通知

每個費率方案最多可設定十個自訂屬性。

瞭解自訂屬性計算

自訂屬性值如何納入費率方案交易次數和收費，取決於收費模式，如下表所示。

充電模式	自訂屬性計算
固定費率和量化費率	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 系統會收取下一個套裝組合 (如有) 的費率。 如果最後一個組合有限制 (並非「無限制」)，且交易超過該限制，會發生以下兩種情況： 開發人員可免費獲得「超過」的金額。 開發人員應用程式會遭到封鎖，無法再呼叫 API，直到方案週期重設為止。 如要進一步瞭解方案重設時間，請參閱「何時會收取週期性費用，以及套裝方案重設時間？」。
可調整的通知	對於可調整的通知，系統會執行以下計算： custom attribute number = amount added to transaction count 舉例來說，如果訊息中的自訂屬性編號為 10，則交易總數會加上 10。

費率方案取得自訂屬性值的位置

交易記錄政策 (在 API 產品組合中) 會告訴營利功能在訊息中尋找自訂屬性值的位置。請在 API 產品組合交易記錄政策的「自訂屬性」部分中定義自訂屬性。

接著，您可以建立 API 產品套裝組合，其中包含交易記錄政策，並在定義自訂屬性後，在費率方案中選取該自訂屬性。

以下是大致流程：

1. 在新增 API 產品時定義自訂屬性。
2. 建立包含該產品的 API 產品套裝組合。
   在 API 產品套裝組合的交易記錄政策中，新增用於定義費率方案的自訂屬性。
3. 為 API 產品套件建立費率方案或可調整的通知，並指定自訂評分參數。

下圖顯示在交易記錄政策中定義的自訂屬性，與費率表方案設定之間的關係。與自訂屬性費率方案關係相關的調整通知也是類似，但不適用於以量級為依據的值。

如何在訊息中產生自訂屬性值

交易記錄政策可以在多個位置尋找自訂屬性值，例如回應標頭、回應主體或回應中的預先定義流程變數。(這項要求無法使用，因為交易必須收到成功回應才算正式。)以下範例說明如何在訊息中加入回應標頭及其數值。無論是哪種情況，我們都會使用「指派訊息」政策搭配變數。

將要求酬載大小新增至回應標頭

在每個訊息要求中，都有一個 client.received.content.length 變數，其中包含要求酬載中的位元組數量。將指派訊息政策附加至 Proxy Endpoint 回應，我們就能產生名為 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 的變數中。您可以使用附加至 Proxy Endpoint 回應的「Assign Message」政策，產生名為 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>

設定費率方案

除了上述自訂屬性設定外，費率方案的設定方式與一般情況相同 (針對不含自訂屬性的費率方案)，但必須遵守下列規定。

使用 UI 設定含有自訂屬性的價目表企劃書

如同下文所述，請使用 Edge UI 或 Classic Edge UI 設定含有自訂屬性的費率表方案。

使用 UI 設定可調整的通知方案，並加入自訂屬性

如需設定可調整的通知方案，請使用自訂屬性，如下所述。

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