設定交易錄製政策

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

為 API 產品套裝組合中的每個 API 產品設定交易記錄政策，詳情請見以下各節。

引言

交易記錄政策可讓營利功能擷取交易參數和自訂屬性。營利功能需要這些資訊才能執行營利程序，例如套用費率方案。

舉例來說，如果您設定收益分潤費率方案，則與營利 API 產品相關的每筆交易所產生的收益，都會與發出要求的應用程式開發人員分享。收益分潤是以交易的淨價格或總價 (您指定價格) 計算，也就是說，系統會使用每筆交易的總收益或淨價格百分比來決定收益分潤。因此，營利需要知道交易的總金額或淨價 (如適用)。系統會根據您在交易記錄政策中所做的設定，取得總金額或淨價。

如果您設定的價目表方案，是透過向開發人員收取每筆交易的費用，可以依據自訂屬性 (例如交易中傳輸的位元組數) 來設定方案費率。營利功能需要知道自訂屬性和位置，才能用於營利。因此，您必須在交易記錄政策中指定自訂屬性。

除了在交易記錄政策中指定交易屬性之外，您還可以指定交易成功條件，判斷交易的成功時間 (供收費)。如需設定交易成功條件的範例，請參閱在交易記錄政策中設定交易成功條件的範例。您也可以為 API 產品指定自訂屬性 (也就是基本費率方案費用)。

設定交易記錄政策

按照下文所述前往「產品組合」頁面。

設定交易屬性

在「交易屬性」部分中，指定營利交易成功的條件。

1. 在「交易成功條件」欄位中，根據狀態屬性值 (如下所述) 指定運算式，以判斷交易成功 (供收費) 的時間點。失敗的交易 (也就是不符合運算式中的條件) 會記錄下來，但不會套用費率方案。範例如下：

   txProviderStatus == 'OK'

2. 「Status」屬性包含「交易成功條件」欄位中設定的運算式使用的值。定義下列欄位來設定 Status 屬性：

   欄位	說明
   API 資源	API 產品中定義的 URI 模式，用於識別營利交易。
   回應位置	指定屬性的回應位置。有效值包括：流程變數、標題、JSON 內文和 XML 內文。
   值	回應的值。如要指定多個值，請按一下「+ 新增」x (例如「+ 新增流程變數」)。

3. 如要設定選用交易屬性，請啟用「Use Optional Attributes」切換鈕，並設定下表中定義的任何交易屬性。

   屬性	說明
   總價	這項屬性僅適用於使用收益分潤模式的房價方案。您必須為這些房價方案選擇總價或淨價。務必以字串類型表示數值。交易的總價。如果是收益分潤方案，您需要記錄總價屬性或淨價格屬性。哪一項是必要屬性，取決於收益分潤因素。舉例來說，您可以設定以交易總價計算的收益分潤費率方案。在這種情況下，「毛利價格」為必填欄位。
   淨價	這項屬性僅適用於使用收益分潤模式的房價方案。您必須為這些房價方案選擇總價或淨價。務必以字串類型表示數值。交易的淨價格。針對收益分潤方案，您需要記錄「淨價格」欄位或「毛價」欄位。至於必填欄位，則要視收益分潤而定。舉例來說，您可以設定以交易淨價為基準的收益分潤費率方案。在這種情況下，「淨價格」為必填欄位。
   幣別	如果房價方案使用收益分潤模式，就必須提供這項屬性。 交易適用的貨幣類型。
   錯誤代碼	與交易相關的錯誤代碼。並提供有關交易失敗的更多資訊。
   商品描述	交易的說明。
   稅金	這個屬性僅適用於收益分潤模型，且必須在 API 呼叫中擷取稅額。務必以字串類型表示數值。交易的稅額。淨價格 (含稅) = 總價。

例如，設定下列值，營利會從訊息回應中的 response.reason.phrase 變數取得流程變數值。如果值允許，而且 API Proxy ProxyEndpoint 要求中附加了營利限制檢查政策，營利狀態就會計為一次交易。

欄位	值
交易成功條件	txProviderStatus == 'OK'
狀態：API 資源	**
狀態：回應位置	流程變數
狀態：流程變數	response.reason.phrase

設定自訂屬性

在「自訂屬性」專區中，您可以找出要納入交易記錄政策的自訂屬性。舉例來說，如果設定價目表方案，並透過每筆交易向開發人員收費，您可以根據自訂屬性 (例如交易中傳輸的位元組數) 來設定方案的費率。接著，您必須將該自訂屬性加入交易記錄政策中。

這些屬性都會儲存在可供查詢的交易記錄中。此外，建立費率方案時也會顯示這些屬性，方便您選擇一或多項屬性做為方案費率依據。

您可以按照在收益摘要報表中加入自訂交易屬性的說明，在收益摘要報表中加入交易記錄政策中定義的自訂屬性。

如要設定自訂屬性，請啟用「使用自訂屬性」切換鈕並定義最多 10 個自訂屬性。您必須針對交易記錄政策中包含的每個自訂屬性指定下列資訊。

欄位	說明
自訂屬性名稱	請輸入用來描述自訂屬性的名稱。如果費率方案是以自訂屬性為依據，系統會在費率方案詳細資料中向使用者顯示這個名稱。舉例來說，如果自訂屬性會擷取時間長度，則應為屬性時間長度命名。 建立自訂屬性費率方案時，系統會在評分單位欄位中設定自訂屬性 (例如小時、分鐘或秒) 的實際單位 (請參閱使用自訂屬性詳細資料指定費率方案)。
API 資源	針對交易中存取的 API 資源，選取一或多個 URI 後置字串 (也就是接在基本路徑後的 URI 片段)。可用資源與交易屬性相同。
回應位置	在回應中選取指定屬性的位置。有效值包括：流程變數、標題、JSON 內文和 XML 內文。
值	指定自訂屬性的值。您指定的每個值都會對應至指定位置中提供自訂屬性的欄位、參數或內容元素。如要指定多個值，請按一下「+ 新增 x」 (例如「+ 新增流程變數」)。 舉例來說，如果您設定一個名為 Content Length 的自訂屬性，並選取「Header」做為回應位置，如果「HTTP Content-Length」欄位提供「Content Length」值，則需指定 Content-Length 做為值。

連結資源與專屬交易 ID

某些交易十分簡單，涉及 API 對某項資源呼叫。不過，其他交易則可能更加複雜。舉例來說，假設在手機遊戲應用程式中購買應用程式內產品的交易涉及多個資源呼叫：

• 呼叫 Reserve API，確保預付使用者有足夠的抵免額購買產品，並分配 (「保留」) 該筆購買的款項。
• 呼叫 charge API，從預付使用者帳戶中扣除資金。

為了處理整個交易，營利功能需要將第一項資源 (對預訂 API 進行與輸出的呼叫和回應) 連結至第二個資源 (針對收費 API 的呼叫和回應)。方法很簡單，它會根據您在「使用專屬交易 ID 連結資源」區段中指定的資訊。

如要設定自訂屬性，請啟用「使用不重複交易 ID」切換鈕並連結交易。針對每個交易，您可以指定資源、回應位置和屬性值，連結至其他交易中對應的值。

舉例來說，假設保留 API 呼叫和收費 API 呼叫的連結如下：預訂 API 回應標頭中名為 session_id 的欄位，對應至 charge API 中名為 reference_id 的回應標頭。在此情況下，您可以在「連結資源」與「不重複的交易 ID」部分設定項目，如下所示：

資源	回應位置	值
reserve/{id}**	標題	session_id
/charge/{id}**	標題	reference_id

設定退款

在退款專區中，您可以指定營利用於處理退款的屬性。

舉例來說，假設使用者透過使用您營利 API 的行動應用程式購買產品。交易會依據共享收益方案營利。不過，假設使用者不滿意產品，並想退回產品。如果產品是透過會退款的 API 呼叫辦理退款，營利狀態會進行必要的營利調整。系統會根據您在交易記錄政策的「退款」一節中指定的資訊執行這項操作。

如要設定退款，請啟用「使用退款屬性」切換鈕，並定義退款詳細資料：

1. 定義下列欄位來定義退款條件：

   欄位	說明
   回應位置	退款交易的資源。如果 API 產品提供多項資源，您可以只選取執行退款的資源。
   退款成功條件	根據狀態屬性值 (如下所述) 的運算式，以判斷退款交易成功的時間 (供收費)。系統會記錄失敗的退款交易 (即不符合運算式中的條件)，但這類交易不會套用費率方案。例如： txProviderStatus == 'OK'

2. 定義下列欄位來設定 Status 屬性：

   欄位	說明
   回應位置	指定屬性的回應位置。有效值包括：流程變數、標題、JSON 內文和 XML 內文。
   值	回應的值。如要指定多個值，請按一下「+ 新增」x (例如「+ 新增流程變數」)。

3. 定義下列欄位來設定父項 ID 屬性：

   欄位	說明
   回應位置	指定屬性的回應位置。有效值包括：流程變數、標題、JSON 內文和 XML 內文。
   值	處理退款的交易 ID。舉例來說，如果使用者購買產品後申請退款，父項交易 ID 就是購買交易的 ID。如要指定多個值，請按一下「+ 新增」x (例如「+ 新增流程變數」)。

4. 如要設定選用的退款屬性，請啟用「Use Optional refund Attributes」切換鈕並設定屬性。選填的退款屬性與設定交易屬性中定義的選用交易屬性相同。

使用 API 管理交易記錄政策

以下各節說明如何使用 API 管理交易記錄政策。

使用 API 建立交易記錄政策

您將交易記錄政策指定為 API 產品的屬性。屬性的值識別：

• 附加交易記錄政策的產品資源 URI 後置字串。後置字串包含一個模式變數，並以大括號括住。API 服務會在執行階段評估模式變數。舉例來說，下列 URI 後置字串包含模式變數 {id}。

  /reserve/{id}**
  

  在這種情況下，API 服務會將資源的 URI 後置字串評估為 /reserve，後接任何以 API 供應商定義 ID 開頭的子目錄。

• 所附加回應中的資源。API 產品可以有多項資源，而每項資源都可以有將交易記錄政策附加至該資源的回應。
• 這項擷取變數政策可讓交易記錄政策針對待擷取的交易參數，從回應訊息擷取內容。

如要將交易記錄政策屬性加入 API 產品，請發出 PUT 要求至 Management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (而非營利 API)。

使用 API 指定交易成功條件

您可以指定交易成功條件，以判斷交易的成功時間 (供收費)。失敗的交易 (即符合運算式中的條件) 都會記錄，但不會套用費率方案。如需設定交易成功條件的範例，請參閱在交易記錄政策中設定交易成功條件的範例。

您將交易成功條件指定為 API 產品的屬性。方法是向 Management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (而非營利 API) 發出 PUT 要求。

舉例來說，在下列要求中，如果 txProviderStatus 的值為 success (醒目顯示交易成功條件相關的規格)，即表示交易成功。

$ curl -H "Content-Type: application/json" -X PUT -d \ 
'{
        "apiResources": [
        "/reserve/{id}**"       
        ],
        "approvalType": "auto",
        "attributes": [                         
        {
                "name": "MINT_TRANSACTION_SUCCESS_CRITERIA",
                "value": "txProviderStatus == 'OK'"
        }
        ],
        "description": "Payment",
        "displayName": "Payment",
        "environments": [
        "dev"
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
        ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

使用 API 指定自訂屬性

您可以為基於基本費率方案費用的 API 產品指定自訂屬性，舉例來說，如果您設定價目表方案，並向開發人員收取每筆交易的費用，您可以根據自訂屬性 (例如交易中傳輸的位元組數) 來設定方案的費率。建立費率方案時，您可以指定一或多個自訂屬性，做為方案費率的基礎。不過，費率方案中的任何特定產品，只能有一個自訂屬性做為方案費率的依據。

您將自訂屬性指定為 API 產品的屬性。方法是向 Management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} (而非營利 API) 發出 PUT 要求。

針對新增至 API 產品的每項自訂屬性，您需要指定名稱和屬性值。名稱格式必須為 MINT_CUSTOM_ATTRIBUTE_{num}，其中 {num} 為整數。

舉例來說，下列要求指定三個自訂屬性。

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
        "apiResources": [
        "/reserve/{id}**",
        "/charge/{id}**"
        ],
        "approvalType": "auto",
        "attributes": [
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_1",
                "value": "test1"
        },
        {
                "name": "MINT_CUSTOM_ATTRIBUTE_2",
                "value": "test2"
        }
 
        ],
        "name": "payment",
        "proxies": [],
        "scopes": [
                ""
        ]
}' \
"https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/payment" \
-u email:password

在交易記錄政策中設定交易成功條件的範例

下表根據交易成功條件運算式和 API Proxy 傳回的 txProviderStatus 值，提供成功和失敗交易的範例。txProviderStatus 是營利用來判斷交易成功的內部變數。

成功條件運算式	運算式是否有效？	API Proxy 的 txProviderStatus 值	評估結果
null	true	"200"	false
""	false	"200"	false
" "	false	"200"	false
"sdfsdfsdf"	false	"200"	false
"txProviderStatus =='100'"	true	"200"	false
"txProviderStatus =='200'"	true	"200"	true
"true"	true	"200"	true
"txProviderStatus=='OK' OR txProviderStatus=='Not Found' OR txProviderStatus=='Bad Request'"	true	"OK"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"OK"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"Not Found"	true
"txProviderStatus matches '(OK)|(Not Found)|(Bad Request)'"	true	"Bad Request"	true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"Bad Request"	true
"(txProviderStatus?:'') matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	null	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"bad request"	true
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"Redirect"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	"heeeelllooo"	false
"txProviderStatus matches '(?i)(OK)|(Not Found)|(Bad Request)'"	true	null	false
"txProviderStatus == 100"	true	"200"	false