配置事务记录政策

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

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

简介

交易记录政策用于启用创收功能,以捕获交易参数和自定义属性。创收功能需要此信息来执行创收处理,例如应用费率方案。

例如,如果您设置了收益分成费率方案,那么涉及您的创收 API 产品的每笔交易所产生的收入百分比将与发出请求的应用的开发者共享。收益分成基于交易的净价格或总价(您需要指定哪一种价格),即用每笔交易的总价或净价的一定百分比来确定收益分成。因此,创收功能需要了解交易的总价或净价(如适用)。它通过您在交易记录政策中的设置获取总价或净价。

如果您设置了一个价目表方案,并对每笔交易向开发者收费,则可以根据自定义属性(例如在交易中传输的字节数)设置方案的费率。变现需要了解什么是自定义属性以及在哪里可以找到自定义属性。因此,您需要在交易记录政策中指定自定义属性。

除了在交易记录政策中指定交易特性之外,您还可以指定交易成功条件,以确定交易何时成功(用于收费)。如需查看设置交易成功条件的示例,请参阅在交易记录政策中设置交易成功条件的示例。您还可以为 API 产品(基础费率方案的收费依据)指定自定义属性。

配置事务记录政策

访问“商品套装”页面,如下所述。

Edge

使用 Edge 界面添加 API 商品套装时,您需要通过执行以下步骤来配置交易记录政策:

  1. 交易记录政策部分选择要配置的 API 产品(如果产品组合中包含多个 API 产品)。
  2. 配置交易属性
  3. 配置自定义属性
  4. 关联具有唯一交易 ID 的资源
  5. 配置退款
  6. 针对 API 产品包中定义的每个 API 产品重复上述步骤。

传统 Edge (Private Cloud)

如需使用传统版 Edge 界面配置事务记录政策,请执行以下操作:

  1. 登录 http://ms-ip:9000,其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。
  2. 在顶部导航栏中依次选择发布 > 商品
  3. 点击适用 API 产品所在行中的 + Transaction Recording Policy。此时会显示“New Transaction Recording Policy”窗口。
  4. 通过执行以下步骤,配置交易记录政策:
  5. 点击保存

配置交易属性

交易属性部分,指定创收交易成功的条件。

  1. 交易成功条件字段中,根据状态属性的值指定表达式(如下所述),以确定交易何时成功(用于收费)。系统会记录未成功(即不符合表达式中的条件)的交易,但不会向其应用费率方案。例如:

    txProviderStatus == 'OK'

  2. Status 属性包含交易成功条件字段中配置的表达式使用的值。通过定义以下字段来配置 Status 属性:
    字段 说明
    API 资源 API 产品中定义的 URI 模式,将用于标识创收交易。
    响应位置 响应指定属性的位置。有效值包括:流变量、标头、JSON 正文和 XML 正文。
    响应的值。要指定多个值,请点击 + 添加“x”(例如,+ 添加流变量)。x
  3. 如需配置可选交易属性,请打开使用可选属性切换开关,并配置下表中定义的任何交易属性。
    属性 说明
    总价

    此属性仅适用于使用收益分成模式的费率方案。 对于这些费率方案,必须提供总价或净价。确保数值表示为字符串类型。交易的总价。对于收益分成方案,您需要记录总价属性或净价属性。必须提供哪个属性取决于收益分成的基础。例如,您可以设置基于交易总价的收益分成费率方案。在这种情况下,“总价”字段是必填字段。

    净价

    此属性仅适用于使用收益分成模式的费率方案。 对于这些费率方案,必须提供总价或净价。确保数值表示为字符串类型。交易的净价。对于收益分成方案,您需要记录“净价”字段或“总价”字段。必填字段取决于收益分成的基础。例如,您可以根据交易净价设置收益分成费率方案。在这种情况下,“净价”字段是必填字段。

    币种

    使用收益分成模式的费率方案必须提供此属性。 交易适用的货币类型。

    错误代码

    与交易相关的错误代码。它提供了有关失败交易的更多信息。

    商品描述

    交易说明。

    税费

    此属性仅与收益分成模式相关,且仅适用于在 API 调用中捕获税费金额的情况。确保数值表示为字符串类型。购买交易的税额。净价加税费 = 总价。

例如,通过设置以下值,创收功能会从消息响应中获取名为 response.reason.phrase 的变量中的数据流变量值。如果值正常,并且 API 代理 ProxyEndpoint 请求附加了创收限制检查政策,创收功能会将其计为交易。

字段
交易成功标准 txProviderStatus == 'OK'
状态:API 资源 **
状态:响应位置 流变量
状态:流变量 response.reason.phrase

配置自定义特性

自定义属性部分中,标识要包含在交易记录政策中的自定义属性。例如,如果您设置了一个价目表方案,并且您需要向开发者收取每笔交易的费用,则可以根据自定义属性(例如在交易中传输的字节数)设置方案的费率。然后,您需要在交易记录政策中添加该自定义特性。

上述每个属性均存储在事务日志中,您可以对其进行查询。创建费率方案时,也会显示这些属性(以便您选择其中一个或多个属性作为方案费率的依据)。

您可以在收入摘要报告中添加交易记录政策中定义的自定义属性,如在收入摘要报告中包含自定义交易属性中所述。

如需配置自定义属性,请打开使用自定义属性切换开关,并定义最多 10 个自定义属性。对于交易记录政策中添加的每个自定义属性,您需要指定以下信息。

字段 说明
自定义属性名称 输入描述自定义属性的名称。如果费率方案基于自定义属性,此名称会在费率方案详情中向用户显示。 例如,如果自定义属性捕获时长,那么您应该将该属性命名为时长。创建自定义属性费率方案时,您可以在评分单位字段中设置自定义属性(例如小时、分钟或秒)的实际单位(请参阅指定具有自定义属性详细信息的费率方案)。
API 资源 选择在事务中访问的 API 资源的一个或多个 URI 后缀(即基本路径后面的 URI 片段)。可用资源与交易属性相同。
响应位置 在响应中选择指定该属性的位置。有效值包括:流变量、标头、JSON 正文和 XML 正文。
指定自定义属性的值。您指定的每个值都对应一个字段、参数或内容元素,用于在您指定的位置提供自定义属性。若要指定多个值,请点击 + 添加“x”(例如,+ 添加流变量)。x

例如,如果您配置一个名为“内容长度”的自定义属性并选择“标头”作为响应位置,那么如果 HTTP Content-Length 字段中提供了“内容长度”值,则您要指定 Content-Length 作为值。

有些事务很简单,涉及对一个资源进行 API 调用。但是,其他事务可能更复杂。例如,假设在移动游戏应用中购买应用内商品的交易涉及多次资源调用:

  • 调用预留 API,该 API 用于确保预付费用户有足够的赠金来购买相应商品,并为购买分配(“预留”)资金。
  • 对费用 API 的调用,此 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 产品提供多项资源,您可以只选择执行退款的资源。
    退款成功标准 基于 Status 属性的值(如下所述)的表达式,用于确定退款交易的成功时间(用于收费)。系统会记录未成功(即不符合表达式中的条件)的退款交易,但系统不会对这些交易应用费率方案。例如:

    txProviderStatus == 'OK'

  2. 通过定义以下字段来配置 Status 属性:
    字段 说明
    响应位置 响应指定属性的位置。有效值包括:流变量、标头、JSON 正文和 XML 正文。
    响应的值。要指定多个值,请点击 + 添加“x”(例如,+ 添加流变量)。x
  3. 通过定义以下字段来配置 Parent ID 属性:
    字段 说明
    响应位置 响应指定属性的位置。有效值包括:流变量、标头、JSON 正文和 XML 正文。
    需要处理退款的交易的 ID。例如,如果用户购买了产品,然后申请退款,则父级交易 ID 就是购买交易的 ID。要指定多个值,请点击 + 添加“x”(例如,+ 添加流变量)。x
  4. 如需配置可选的退款属性,请启用 Use Optional Refund Attributes 切换开关,并配置相应属性。可选的退款属性与可选交易属性相同,具体定义请参见配置交易属性

使用 API 管理交易记录政策

以下各部分介绍了如何使用 API 管理交易记录政策。

使用 API 创建交易记录政策

您可以将交易记录政策指定为 API 产品的属性。该属性的值标识:

  • 交易记录政策附加到的商品资源的 URI 后缀。后缀包含一个用大括号括起来的模式变量。API 服务会在运行时评估模式变量。例如,以下 URI 后缀包含模式变量 {id}
    /reserve/{id}**
    

    在这种情况下,API 服务会将资源的 URI 后缀评估为 /reserve,后跟以 API 提供方定义的 ID 开头的所有子目录。

  • 附加到响应中的资源。一个 API 产品可以有多个资源,每个资源都可以有一个附加到该资源响应的事务记录政策。
  • 提取变量政策,使交易记录政策能够从您要捕获的交易参数的响应消息中提取内容。

您可以通过向 Management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id}(而不是变现 API)发出 PUT 请求,来为 API 产品添加交易记录政策属性。

使用 API 指定交易成功标准

您可以指定事务成功标准,以确定事务何时成功(用于收费)。系统会记录未成功(即符合表达式中的条件)的交易,但不会向其应用费率方案。如需查看设置交易成功条件的示例,请参阅在交易记录政策中设置交易成功条件的示例

您可以将交易成功标准指定为 API 产品的属性。为此,请向 Management API https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts/{apiproduct_Id}(而不是 monetization 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}(而不是 monetization 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 是创收功能用于确定交易成功与否的内部变量。

成功条件表达式 表达式有效? API 代理中的 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