配置事务记录政策

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

为 API 产品软件包中的每个 API 产品配置交易记录政策，如以下部分所述。

简介

交易记录政策可让获利功能捕获交易参数和自定义属性。获利功能需要这些信息才能执行其获利处理，例如应用价格方案。

例如，如果您设置了收益分成费率方案，那么涉及您的创收 API 产品的每笔交易产生的收益中，将有一部分百分比与发出请求的应用的开发者分成。收益分成基于交易的净价或总价（由您指定），也就是说，每笔交易的总价或净价的百分比用于确定收益分成。因此，创收功能需要知道交易的总价或净价（如适用）。它会从您在交易记录政策中所做的设置中获取总价或净价。

如果您设置了费率卡方案（即针对每笔交易向开发者收费），则可以根据自定义属性（例如交易中传输的字节数）设置该方案的费率。 创收功能需要知道自定义属性是什么以及在哪里可以找到它。因此，您需要在交易记录政策中指定自定义属性。

除了在交易记录政策中指定交易属性之外，您还可以指定交易成功标准，以确定交易何时成功（用于收费）。如需查看设置交易成功标准的示例，请参阅在交易记录政策中设置交易成功标准的示例。您还可以为 API 产品（您根据该产品确定费率方案费用）指定自定义属性。

配置交易记录政策

访问“产品套装”页面，如下所述。

配置交易属性

在交易属性部分中，指定表明交易成功获利的条件。

1. 在交易成功标准字段中，指定一个基于状态属性（将在下文中介绍）值的表达式，用于确定交易何时成功（以便进行扣款）。系统会记录不成功的交易（即不符合表达式中的条件），但不会对这些交易应用费率方案。例如：

   txProviderStatus == 'OK'

2. 状态属性包含在交易成功条件字段中配置的表达式所使用的值。通过定义以下字段来配置状态属性：

   字段	说明
   API 资源	API 产品中定义的 URI 模式，将用于识别创收交易。
   回答位置	指定属性的响应的位置。有效值包括：流变量、标头、JSON 正文和 XML 正文。
   值	回答的价值。如需指定多个值，请点击 + 添加 x（例如，+ 添加流程变量）。

3. 如需配置可选的交易属性，请启用使用可选属性切换开关，并配置下表中定义的任何交易属性。

   属性	说明
   总价	此属性仅适用于采用收入分成模式的费率方案。 对于这些费率方案，必须提供总价或净价。确保数值以 String 类型表示。交易的总价。对于收益分成方案，您需要记录“含税价格”属性或“不含税价格”属性。需要提供哪个属性取决于收益分成的基础。例如，您可以设置基于交易总价的收益分成费率方案。在这种情况下，“总价”字段为必填字段。
   净价	此属性仅适用于采用收入分成模式的费率方案。 对于这些费率方案，必须提供总价或净价。确保数值以 String 类型表示。交易的净价格。对于收益分成方案，您需要记录“净价”字段或“总价”字段。具体需要哪个字段取决于收益分成的基础。例如，您可以设置基于交易净价的收益分成费率方案。 在这种情况下，“净价”字段为必填字段。
   货币	对于使用收益分成模式的费率方案，此属性是必需的。 适用于交易的币种类型。
   错误代码	与交易相关的错误代码。它提供有关失败交易的更多信息。
   商品描述	交易说明。
   税费	此属性仅适用于收入分成模式，并且仅当 API 调用中捕获了税费金额时才适用。确保数值以字符串类型表示。购买交易的税额。净价加税费等于含税价。

例如，通过设置以下值，创收功能可从名为 response.reason.phrase 的变量中的消息响应获取流变量的值。如果值为 OK，并且 Monetization Limits Check 政策已附加到 API 代理 ProxyEndpoint 请求，则创收功能会将此视为一笔交易。

配置自定义属性

在自定义属性部分中，您可以指定要纳入交易记录政策中的自定义属性。例如，如果您设置了费率卡方案，并按每笔交易向开发者收费，则可以根据自定义属性（例如交易中传输的字节数）设置方案的费率。然后，您需要在交易记录政策中添加该自定义属性。

这些属性中的每一个都存储在事务日志中，您可以查询该日志。此外，当您创建价格方案时，系统也会显示这些属性（以便您选择一个或多个属性作为方案价格的依据）。

您可以按照在收入摘要报告中添加自定义交易属性中的说明，在收入摘要报告中添加交易记录政策中定义的自定义属性。

如需配置自定义属性，请启用使用自定义属性切换开关，然后定义最多 10 个自定义属性。对于您在交易记录政策中包含的每个自定义属性，您都需要指定以下信息。

关联具有唯一交易 ID 的资源

有些交易很简单，只涉及对一个资源的 API 调用。不过，其他交易可能更为复杂。例如，假设在移动游戏应用中购买应用内商品的交易涉及多个资源调用：

• 对预留 API 的调用，用于确保预付费用户有足够的信用额度来购买产品，并为购买交易分配（“预留”）资金。
• 对扣款 API 的调用，用于从预付费用户的账号中扣除资金。

为了处理整个交易，创收需要一种方法来关联第一个资源（与预留 API 之间的调用和响应）与第二个资源（与扣款 API 之间的调用和响应）。为此，它依赖于您在将资源与唯一交易 ID 相关联部分中指定的信息。

如需配置自定义属性，请启用使用唯一交易 ID 开关并关联交易。对于每项交易，您需要指定资源、响应位置和属性值，这些值会与其他交易中的相应值相关联。

例如，假设预留 API 调用和扣款 API 调用按如下方式关联：预留 API 的响应标头中名为 session_id 的字段对应于扣款 API 的响应标头中名为 reference_id 的字段。在这种情况下，您可以按如下方式设置“将资源与唯一交易 ID 相关联”部分中的条目：

配置退款

在“退款”部分，您可以指定变现用于处理退款的属性。

例如，假设用户通过使用您的创收型 API 的移动应用购买了某件商品。交易根据共享收入方案创收。不过，假设用户对产品不满意，想要退货。如果通过调用您的 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 https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id}（而非创收 API）发出 PUT 请求，将交易记录政策属性添加到 API 产品。

使用 API 指定交易成功标准

您可以指定交易成功标准，以确定交易何时成功（用于扣款）。系统会记录不成功的交易（即符合表达式中的条件），但不会对这些交易应用费率方案。如需查看设置交易成功标准的示例，请参阅在交易记录政策中设置交易成功标准的示例。

您可以将交易成功标准指定为 API 产品的属性。为此，请向管理 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 产品的属性。为此，请向管理 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 代理返回的 txProviderStatus 值，提供了成功和不成功交易的示例。txProviderStatus 是获利功能用于确定交易是否成功的内部变量。