您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
引言
在某些情況下,您可能需要根據變數或自訂值建立交易計數器。 舉例來說,您可能需要:
- 根據 API 呼叫訊息中提供的值,向開發人員收取變動金額。舉例來說,您可能會想根據 API 要求中傳輸的位元組數,向應用程式開發人員收費。
- 將多個 API 呼叫納入單筆交易中。
使用含有自訂屬性的費率方案之後,您就能在 API 呼叫的訊息中識別計數器,該呼叫會用來計算交易次數和費用。
系統支援下列包含自訂屬性的費率方案:
- 包含自訂屬性的價目表
- 提供自訂屬性的可調整通知
每個費率方案最多可設定 10 個自訂屬性。
瞭解自訂屬性的計算方式
系統如何將自訂屬性值計入費率方案的交易次數和費用,如下表所示。
充電模式 | 自訂屬性計算 |
---|---|
固定費率和體積 |
如果是固定費率,自訂屬性編號就會成為交易次數乘以費率後得出的金額。如為體內頻帶,頻帶中的交易次數會按照自訂屬性編號遞增,開發人員必須針對該交易次數付費。舉例來說,如果訊息中的自訂屬性值是 10,系統就會向開發人員收取 10 筆交易的費用,並將 10 筆交易計入目前的區間數量。如果開發人員在目前的頻帶只有 6 筆交易, 6 乘以該頻帶的速率。剩下的 4 則會進入下一個錶帶,並乘以該頻帶的速率。 在磁碟區頻帶方案中,如果最後一個音量頻帶設有限制 (非「無限制」),且交易超出該限制,就會發生兩個情況:
|
組合 |
由於套裝組合的收費是依據群組收費 (而非交易),因此會發生以下計算:
舉例來說,如果訊息中的自訂屬性編號為 10,那麼在組合中使用的交易次數中會增加 10。如果開發人員在目前的套裝組合中只剩下 6 筆交易,系統就會填入該套裝組合,下一個套裝組合數量會增加 4。系統會按照下一個套裝組合的費率 (如有)。 如果最後一個組合設有限制 (非「無限制」),且交易超出該限制,會發生以下兩個情況:
|
可調整的通知 |
可調整通知進行以下計算:
舉例來說,如果訊息中的自訂屬性編號為 10,則交易總數會增加 10 個。 |
費率方案取得自訂屬性值的位置
交易記錄政策 (適用於 API 產品套裝組合) 會指示營利該到何處查看自訂屬性值的訊息。您會在 API 產品套裝組合的交易記錄政策的「自訂屬性」部分中定義自訂屬性。
之後,您就能在費率方案中選取該自訂屬性。您建立了包含交易記錄政策且已定義的自訂屬性的 API 產品套裝組合後,
大致流程如下:
- 新增 API 產品時定義自訂屬性。
- 建立包含該產品的 API 產品套裝組合。
在 API 產品套裝組合的交易記錄政策中,新增將用於定義費率方案的自訂屬性。 - 為 API 產品套裝組合建立價目表類型或可調整通知,並指定自訂評分參數。
下圖顯示交易記錄政策中定義的自訂屬性與價目表方案設定之間的關係。採用自訂屬性費率方案關係的可調整通知類似,但不適用大量用量的值。
如何在訊息中產生自訂屬性值
交易記錄政策可以在許多地方尋找自訂屬性值,例如回應標頭、回應主體或回應中的預先定義流程變數。(由於在您收到成功回應前,交易可能不是正式的,因此無法使用要求)。以下範例說明如何在訊息中加入回應標頭及其數值。在這兩種情況下,我們將與變數搭配使用「Assign Message」政策。
將要求酬載大小新增至回應標頭
在每個訊息要求中,都有 client.received.content.length
變數,內含要求酬載中的位元組數。只要將「指派訊息」政策附加至 Proxy 端點回應,即可產生名為 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
的自訂屬性,如下所示:
使用 Verify API 金鑰政策 (營利的必要項目) 時,這個值會儲存在名為 verifyapikey.{policy_name}.apprating
的變數中。使用附加至 Proxy 端點回應的「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>
設定房價方案
除了上述自訂屬性設定之外,費率方案的設定方式與平常相同 (適用於不含自訂屬性的房價方案),但必須遵守下列規定。
透過使用者介面設定含有自訂屬性的價目表方案
透過 Edge UI 或傳統版 Edge UI 設定含有自訂屬性的價目表方案,詳情請見以下各節。
Edge
如何透過 Edge UI 設定包含自訂屬性的價目表方案:
- 新增 API 產品時定義自訂屬性。
- 建立包含該產品的 API 產品套裝組合。請參閱「建立 API 產品套裝組合」一文。
在 API 產品套裝組合的交易記錄政策中,新增將用來定義費率方案的自訂屬性。詳情請參閱本主題的簡介,以及「建立交易記錄政策」。 - 為 API 產品套裝組合建立費率方案,並指定自訂評分參數。
詳情請參閱透過使用者介面設定價目表詳細資料。
傳統邊緣 (Private Cloud)
請按照下列步驟,透過傳統版 Edge UI 使用自訂屬性方案,以自訂屬性方案建立價目表:
- 在 API 產品的交易記錄政策中,新增將用於定義費率方案的自訂屬性。詳情請參閱本主題的簡介,以及「建立交易記錄政策」。如要加入 API 套件,請針對每項 API 產品執行這項作業。
- 按照您想要的方式設定 API 產品和交易記錄政策後,請建立包含該產品的 API 套件。請參閱「建立 API 套件」一文。
- 為 API 套件建立費率方案,然後選取「Rate Card」的「Rate Card」類型類型。
-
按一下「價目表」連結。系統會開啟「價目表」視窗。
- 在「自訂屬性」下拉式選單中選取自訂屬性。選單會列出在交易記錄政策中為產品建立的自訂屬性。開發人員在每筆交易中,會根據所選自訂屬性的值收費。
(屬性值 * 費率 = 向開發人員收取的費用) - 視需要按照「指定價目表方案詳細資料」的說明設定免費增值方案。
- 按照「指定價目表方案詳細資料」的說明設定充電模式。不過請注意,對於含有自訂屬性費率方案類型的價目表,系統會根據您選取的自訂屬性計費。舉例來說,如果您選擇以固定費率做為收費模式,開發人員會根據自訂屬性收取固定費率,例如每筆交易傳輸的位元組數 (而非每筆交易的固定費率)。詳情請參閱「計算」一節。
-
按一下「儲存草稿」。
請在確定企劃書尚未確定時再發布企劃書。如要瞭解如何設定發布日期及發布方案,請參閱「發布費率方案」。
詳情請參閱 透過使用者介面指定價目表方案詳細資料。
透過使用者介面,以自訂屬性設定可調整的通知計畫
使用自訂屬性設定可調整的通知計畫,如下所述。邊緣
如何透過 Edge UI 設定包含自訂屬性的價目表方案:
- 新增 API 產品時定義自訂屬性。
- 建立包含該產品的 API 產品套裝組合。請參閱「建立 API 產品套裝組合」一文。
在 API 產品套裝組合的交易記錄政策中,新增將用來定義費率方案的自訂屬性。詳情請參閱本主題的簡介,以及「建立交易記錄政策」。 - 為 API 產品套裝組合建立費率方案,並指定自訂評分參數。
詳情請參閱「使用 UI 設定可調整的通知方案」。
傳統邊緣 (Private Cloud)
如要透過傳統版 Edge UI 設定含有自訂屬性的價目表方案,請按照下列步驟操作:
- 在 API 產品的交易記錄政策中,新增將用於定義費率方案的自訂屬性。詳情請參閱本主題的簡介,以及「建立交易記錄政策」。如要加入 API 套件,請針對每項 API 產品執行這項作業。
- 按照您想要的方式設定 API 產品和交易記錄政策後,請建立包含該產品的 API 套件。請參閱「建立 API 套件」一文。
- 為 API 套件建立費率方案,然後選取「Adjustable Notification with Custom Attribute」的費率方案類型。
-
按一下「詳細資料」連結。「可調整通知」視窗隨即開啟。
- 在「自訂屬性」下拉式選單中選取自訂屬性。選單會列出在交易記錄政策中為產品建立的自訂屬性。開發人員的交易總數是以每筆交易中所選自訂屬性的值計算。
- 將「匯總基礎」設為匯總交易次數的時間範圍。選取介於 1 到 24 個月之間的數字。這個值預設為 1 個月。
- 按一下「套用並關閉」。
-
按一下「儲存草稿」。
請在確定企劃書尚未確定時再發布企劃書。如要瞭解如何設定發布日期及發布方案,請參閱「發布費率方案」。
詳情請參閱「 使用 UI 指定可調整的通知方案詳細資料」。
使用 API 指定使用自訂屬性的費率方案詳細資料
請執行以下必要步驟:
- 在 API 產品的交易記錄政策中,新增將用於定義費率方案的自訂屬性。詳情請參閱本主題的簡介,以及「建立交易記錄政策」。如要加入 API 套件,請針對每項 API 產品執行這項作業。
- 按照您想要的方式設定 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