設定交易錄製政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

如要為 API 產品組合中的每個 API 產品設定交易記錄政策，請參閱下列各節。

簡介

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

舉例來說，如果您設定收益分潤費率方案，系統會將每筆交易產生的收益 (涉及營利 API 產品) 的一部分，分給發出要求的應用程式開發人員。收益分潤是根據交易的淨價或總價 (由你指定) 計算，也就是說，系統會根據每筆交易的總價或淨價百分比，決定收益分潤。因此，營利功能需要知道交易的總價或淨價 (視情況而定)。系統會根據您在交易記錄政策中設定的內容，取得總價或淨價。

如果您設定費率表方案，向開發人員收取每筆交易的費用，可以根據自訂屬性 (例如交易中傳輸的位元組數)，設定方案的費率。營利功能需要知道自訂屬性為何，以及該屬性位於何處。因此，您需要在交易記錄政策中指定自訂屬性。

除了在交易記錄政策中指定交易屬性，您也可以指定交易成功標準，判斷交易何時成功 (用於收費)。如需設定交易成功條件的範例，請參閱「交易記錄政策中設定交易成功條件的範例」。您也可以為 API 產品指定自訂屬性 (費率方案費用依此計算)。

設定交易記錄政策

存取「產品組合」頁面，如下所述。

設定交易屬性

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

1. 在「交易成功條件」欄位中，根據「狀態」屬性的值 (詳見下節) 指定運算式，判斷交易何時成功 (以利收費)。系統會記錄未成功的交易 (即不符合運算式中的條件)，但不會套用費率方案。例如：

   txProviderStatus == 'OK'

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

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

3. 如要設定選填交易屬性，請啟用「使用選填屬性」切換鈕，然後設定下表定義的任何交易屬性。

   屬性	說明
   總價	這項屬性僅適用於採用收益分享模式的費率方案。 這類房價方案必須提供總價或淨價。請確保數值以字串類型表示。交易的總價。如果是收益分潤方案，則必須記錄「原價」屬性或「淨價」屬性。所需屬性取決於收益分潤的依據。舉例來說，你可以根據交易總價設定收益分潤費率方案。這種情況下，「含稅價」欄位為必填。
   淨價	這項屬性僅適用於採用收益分享模式的費率方案。 這類房價方案必須提供總價或淨價。請確保數值以字串類型表示。交易的淨價。如果是收益分潤方案，您必須記錄「淨價」欄位或「總價」欄位。視收益分潤的依據而定，所需欄位也會有所不同。舉例來說，您可以根據交易淨價設定收益分潤費率方案。在這種情況下，「淨價」欄位為必填。
   幣別	如果費率方案採用收益分潤模式，則必須提供這項屬性。 交易適用的貨幣類型。
   錯誤代碼	與交易相關的錯誤代碼。提供交易失敗的詳細資訊。
   商品描述	交易說明。
   稅金	這項屬性僅適用於收益分潤模式，且只有在 API 呼叫中擷取稅額時才相關。請確認數值是以字串類型表示。購買交易的稅額。淨價加上稅金等於總價。

舉例來說，設定下列值後，營利功能會從名為 response.reason.phrase 的變數中，取得訊息回覆的流程變數值。如果值為「OK」，且 營利限制檢查政策已附加至 API Proxy ProxyEndpoint 要求，營利會將其計為交易。

設定自訂屬性

在「自訂屬性」部分，找出要納入交易記錄政策的自訂屬性。舉例來說，如果您設定費率表方案，向開發人員收取每筆交易的費用，可以根據自訂屬性 (例如交易中傳輸的位元組數)，設定方案的費率。然後，您需要在交易記錄政策中加入該自訂屬性。

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

如要將交易記錄政策中定義的自訂屬性納入收益摘要報表，請參閱「在收益摘要報表中加入自訂交易屬性」一文。

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

連結具有專屬交易 ID 的資源

有些交易很簡單，只要呼叫一個資源的 API 即可。不過，其他交易可能更為複雜。舉例來說，假設在行動遊戲應用程式中購買應用程式內商品的交易涉及多項資源呼叫：

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

如要處理整筆交易，營利功能必須將第一個資源 (呼叫和回應預留 API) 與第二個資源 (呼叫和回應收費 API) 連結。為此，系統會依據您在「使用專屬交易 ID 連結資源」部分指定的資訊進行比對。

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

舉例來說，假設預訂 API 呼叫和收費 API 呼叫的連結如下：預訂 API 回應標頭中名為 session_id 的欄位，對應於收費 API 中名為 reference_id 的回應標頭。在這種情況下，您可能會將「使用不重複交易 ID 連結資源」部分中的項目設為如下：

設定退款

在「退款」部分，您可以指定屬性，供營利功能處理退款。

舉例來說，假設使用者透過使用您營利 API 的行動應用程式購買產品，系統會根據共用收益方案，為交易營利。但假設使用者對產品不滿意，想要退貨，如果透過 API 呼叫退款，營利功能會進行必要的營利調整。系統會根據您在交易記錄政策的「退款」部分中指定的資訊，執行這項操作。

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

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

   欄位	說明
   回覆位置	退款交易的資源。如果 API 產品提供多項資源，您可以只選取執行退款的資源。
   退款成功標準	根據「狀態」屬性的值 (詳見下文) 判斷退款交易是否成功 (用於收費)。系統會記錄未成功的退款交易 (即不符合運算式中的條件)，但不會套用費率方案。例如： txProviderStatus == 'OK'

2. 定義下列欄位，設定「狀態」屬性：

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

3. 定義下列欄位，設定「父項 ID」屬性：

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

4. 如要設定選填退款屬性，請啟用「使用選填退款屬性」切換鈕，然後設定屬性。選填退款屬性與選填交易屬性相同，如「設定交易屬性」一文所述。

使用 API 管理交易記錄政策

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

使用 API 建立交易記錄政策

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

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

  /reserve/{id}**

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

• 附加至回應中的資源。API 產品可以有多個資源，每個資源都可以附加交易記錄政策，用於記錄該資源的回應。
• 擷取變數政策，可讓交易記錄政策從回應訊息中擷取內容，做為您要擷取的交易參數。

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

使用 API 指定交易成功條件

您可以指定交易成功標準，判斷交易何時成功 (以利收費)。系統會記錄未成功的交易 (即符合運算式中的條件)，但不會套用費率方案。如需設定交易成功條件的範例，請參閱「在交易記錄政策中設定交易成功條件的範例」。

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

舉例來說，在下列要求中，如果 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 產品的屬性。方法是向管理 API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id} 發出 PUT 要求 (而非向營利 API 發出要求)。

為 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 是營利功能用來判斷交易是否成功的內部變數。