管理报告

您正在查看 Apigee Edge 文档。
请查看 Apigee X 文档

简介

启用创收报告后,您可以访问重点使用情况信息和交易活动。 例如,您可以确定在指定日期范围内哪些应用、开发者、API 产品套装或 API 产品有交易活动。您可以利用创收功能生成用于跟踪 API 用量的摘要详细报告。

创收报告的类型

您可以生成以下类型的创收报告。

报告 说明
结算 查看开发者在单个结算月份的活动,并验证费率方案是否已正确应用。
预付款余额 查看预付开发者在结算月份或当前开放月份内进行充值的余额,以便核对从付款处理方收到的付款。
收入 查看开发者在某个日期范围内的活动和收入,以便分析开发者(及其应用)的 API 产品软件包和产品的表现。
方差

比较开发者在两个日期范围内产生的活动和收入,以便分析开发者(及其应用)的 API 软件包和产品的性能上调或下降趋势。

数据保留功能简介

在 Apigee Edge 公有云中,创收数据保留是一项计划权利。请访问 https://cloud.google.com/apigee/specsheets 查看创收权利。如果您希望在许可期之后保留创收数据,请与 Apigee 销售团队联系。扩展的数据保留期限是在请求时启用,无法追溯启用以包含早于原始数据保留期限的数据。

探索“创收报告”页面

如下文所述,访问创收报告页面。

边缘

如需使用 Edge 界面访问“报告”页面,请执行以下操作:

  1. 登录 apigee.com/edge
  2. 在左侧导航栏中,依次选择发布 > 创收 > 报告

系统随即会显示“报告”页面。

如图所示,“报告”页面让您可以:

传统版 Edge(私有云)

如需使用传统版 Edge 界面访问“报告”页面,请执行以下操作:

  1. 登录 http://ms-ip:9000,其中 ms-ip 是管理服务器节点的 IP 地址或 DNS 名称。
  2. 选择顶部导航栏中的创收 > 创收报告

系统随即会显示“报告”页面。

配置报告

使用界面配置报告,如以下部分所述。

配置报告的步骤

使用 Edge 界面或传统 Edge 界面配置报告。

边缘

如需使用 Edge 界面配置报告,请执行以下操作:

  1. 在左侧导航栏中,依次选择发布 > 创收 > 报告
  2. 点击 + 报告
  3. 配置下表中定义的报告详细信息。
    字段 说明
    名称 报告的唯一名称。
    说明 报告的说明。
    报告类型 请参阅创收报告的类型
  4. 根据所选的结算类型配置其余的报告详细信息,具体如以下部分所述:
  5. 在报告窗口中输入相应信息后,您可以:
    • 点击保存报告,保存报告配置。
    • 如需仅查看详细报告,请点击提交作业以异步方式运行报告,并在稍后检索结果。 如需了解详情,请参阅生成和下载报告

    • 点击另存为 CSV另存为 Zip 文件,将生成的报告以逗号分隔值 (CSV) 或包含 CSV 格式的压缩 ZIP 文件下载到本地机器上。对于大型报告,建议使用 Zip 格式的下载报告,这样会更有效地进行下载。

传统版 Edge(私有云)

如需使用传统版 Edge 界面创建报告,请执行以下操作:

  1. 选择顶部导航栏中的创收 > 创收报告
  2. 在下拉菜单中,选择要创建的报告类型。请参阅创收报告的类型
  3. 点击 + 报告
  4. 根据所选结算类型配置报告详情,如以下部分所述:
  5. 在报告窗口中输入相应信息后,您可以:
    • 点击另存为...可保存报告配置,以便日后下载报告。
    • 如需仅查看详细报告,请点击提交作业以异步方式生成报告,稍后再检索结果。 如需了解详情,请参阅生成和下载报告

    • 点击下载 CSV 文件,以生成逗号分隔值 (CSV) 文件以供查看,并将报告下载到本地机器。

配置结算报告

按照配置报告的步骤进行操作,然后在报告页面中输入以下信息:

字段 说明
结算月份

报告的结算月份。

报告级

报告级别。有效值包括:

  • 详细:在单独的行中显示每笔交易,并允许您检查费率方案是否已正确应用。没有摘要。
  • 摘要:总结了每个 API 产品和开发者的总收入。
商品套装

注意:在传统边缘界面中,API 产品软件包称为 API 软件包。

选择要纳入到报告中的 API 产品软件包。如果未选择任何选项,报告中将包含所有 API 产品软件包。

此报告包含与所选的每个 API 产品捆绑包对应的单独一行。

对于摘要报告,您可以视需要选择在“摘要显示”选项中选择不显示。在这种情况下,报告会汇总(或选定)所有 API 产品软件包的信息(不会单独列出每个 API 产品软件包的信息)。

产品

选择要纳入到报告中的 API 产品。如果未选择任何 API,报告将包含所有 API 产品。

此报告包含每个选定 API 产品的单独一行。

对于摘要报告,您可以视需要选择在“摘要显示”选项中选择不显示。在这种情况下,该报告会汇总(或选定的)所有开发者的信息(不会单独列出每个所选开发者的信息)。

公司

请选择要包含在报告中的公司。如果未选择任何报告,报告将包含所有公司。

费率方案

费率方案中要包含在报告中。请选择以下选项之一:

  • 所有费率方案:在报表中添加所有费率方案。
  • 标准费率方案:报表中仅包含标准费率方案。
  • 开发者专用费率方案:报表中仅包含开发者方案。

配置预付费余额报告

按照配置报告的步骤进行操作,然后在报告页面中输入以下信息:

字段 说明
结算月份

报告的结算月份。

报告级

报告级别。有效值包括:

  • 明细:单独显示各个余额充值,并对付款处理方收到的付款进行对帐。
  • 摘要:汇总了每个开发者的充值总数。
公司

请选择要包含在报告中的公司。如果未选择任何报告,报告将包含所有公司。

配置收入报告

按照配置报告的步骤进行操作,然后在报告页面中输入以下信息:

字段 说明
日期范围

报告的日期范围。请选择以下选项之一:

  • 预设:从下拉菜单中选择一个标准日期范围(例如上一个日历月)。
  • 自定义:从日历弹出式窗口中为范围选择开始日期和结束日期。
选择币种

报告所用的货币。有效值包括:

  • 本地货币:报告中的每一行都按照适用的费率方案显示。也就是说,如果开发者的方案使用不同的货币,则一份报告中可能会有多个货币。
  • 欧元:报告中的本地货币交易是以欧元换算和显示的。
  • 英镑:报告中的本地货币交易会换算成以英镑为单位的交易。
  • 美元:报告中的本地货币交易会换算成美元币种。
报告级

报告级别。有效值包括:

  • 详细:在单独的行中显示每笔交易。没有摘要。
  • 摘要:汇总了每个 API 产品和开发者的总收入,具体取决于您选择的参数。
商品套装

注意:在传统边缘界面中,API 产品软件包称为 API 软件包。

选择要纳入到报告中的 API 产品软件包。如果未选择任何选项,报告中将包含所有 API 产品软件包。

此报告包含与所选的每个 API 产品捆绑包对应的单独一行。

对于摘要报告,您可以视需要选择在“摘要显示”选项中选择不显示。在这种情况下,报告会汇总(或选定)所有 API 产品软件包的信息(不会单独列出每个 API 产品软件包的信息)。

产品

选择要纳入到报告中的 API 产品。如果未选择任何 API,报告将包含所有 API 产品。

此报告包含每个选定 API 产品的单独一行。

对于摘要报告,您可以视需要选择在“摘要显示”选项中选择不显示。在这种情况下,该报告会汇总(或选定的)所有开发者的信息(不会单独列出每个所选开发者的信息)。

公司

请选择要包含在报告中的公司。如果未选择任何报告,报告将包含所有公司。

对于摘要报告,您可以视需要在“摘要显示选项”部分中选中不显示。 在这种情况下,报告会汇总所有(或选定)公司的信息(不会单独列出每个选定公司的信息)。

应用

选择要纳入到报告中的应用。如果未选择任何报告,报告将包含所有应用。

此报告会针对每个所选应用显示单独的一行。

对于摘要报告,您可以视需要在“摘要显示选项”部分中选中不显示。在这种情况下,该报告会汇总(或所选的)所有应用的信息,而不会单独列出每个所选应用的信息。

摘要显示选项

对列进行分组和在报告中显示的顺序。选择一个数字,用于表示该分组在分组中的相对顺序(1 表示第一个分组)。例如,下面的先是按软件包、产品、开发者、应用对报告进行分组。

如果您不想显示某个部分,请选择不显示,然后按顺序选择其余字段。当您更改某一部分的相对顺序或选择不在报告中显示某个部分时,该顺序会自动更新。

在收入摘要报告中包含自定义交易属性

通过使用交易记录政策,您可以从交易捕获自定义特性数据,并将这些摘要特性添加到摘要收入报告中。为您的组织设置 MINT.SUMMARY_CUSTOM_ATTRIBUTES 属性,定义创收数据库表中包含的一组默认自定义属性。

使用此功能需要考虑一些事项并进行规划,因此请查看以下注意事项。

如果您是云客户,请与 Apigee Edge 支持团队联系,以设置该属性。如果您是适用于私有云的 Apigee Edge,请使用系统凭据将 PUT 请求设置为以下 API。

curl -u email:password -X PUT -H "Content-type:application/xml" http://host:port/v1/o/{myorg} -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isMonetizationEnabled">true</Property>
        <Property name="MINT.SUMMARY_CUSTOM_ATTRIBUTES">[&quot;partner_id&quot;,&quot;tax_source&quot;]</Property>
        <Property name="features.topLevelDevelopersAreCompanies">false</Property>
    </Properties>
</Organization>"

在此示例中,API 调用启用了这项功能,并将 partner_idtax_source 列添加到创收数据库中。请注意,API 调用中的自定义属性数组已经过网址编码。

在报告中添加自定义交易属性时的注意事项

  • 在使用 API 创建属性名称之前,请务必先确定要使用的属性名称。这些是数据库中的列名,自定义属性数据始终存储在数据库中。
  • 每项事务记录政策都有 10 个可用的自定义特性槽,如下图所示。为要纳入报告的商品所使用的相同属性使用完全相同的属性名称和位置。例如,在以下事务记录政策中,partner_idtax_source 自定义属性分别占据方框 4 和 5。该名称应包含在所有交易报告政策中,以便纳入报告的产品。

启用此功能后,如需在摘要收入报告中添加自定义属性,请通过将 transactionCustomAttributes 添加到 MintCriteria 来使用报告 API。请参阅条件配置选项

配置方差报告(已弃用)

按照配置报告的步骤进行操作,然后在报告页面中输入以下信息:

字段 说明
日期范围

报告的日期范围。请选择以下选项之一:

  • 预设:从下拉菜单中选择一个标准日期范围(例如上一个日历月)。
  • 自定义:从日历弹出式窗口中为范围选择开始日期和结束日期。
软件包

要纳入到报告的 API 软件包。请选择以下选项之一:

  • 所有应用:包含报告中的所有 API 软件包。
  • 已选择:显示了一个列表,您可以从中选择要包含在报告中的 API 软件包。如果您不选择任何软件包,则所有软件包都会包含在报告中。

此报告包含每个选定 API 软件包的单独一行。

对于摘要报告,您可以视需要在“摘要显示选项”部分中选中“不显示(软件包)”。在这种情况下,报告会汇总(或选定)所有 API 软件包的信息,但不会单独列出每个 API 软件包的信息。

产品

要纳入报告的 API 产品。请选择以下选项之一:

  • 全部:包含报告中的所有 API 产品。
  • 已选择:显示了一个列表,您可以从中选择要包含在报告中的产品。如果您不选择任何产品,此报告中会包含所有产品。

此报告包含每个选定 API 产品的单独一行。

对于摘要报告,您可以视需要在“摘要显示选项”部分中选中“不显示(商品)”。在这种情况下,报告会汇总(或选定)所有 API 产品的信息(不会单独列出每个 API 产品的信息)。

公司

要纳入到报告中的公司。请选择以下选项之一:

  • 全部:包含报告中的所有公司。
  • 已选择:显示了一个列表,您可以从中选择要在报告中包含的公司。如果您不选择任何公司,则报告中会包含所有公司。

此报告包含每个选定公司的单独一行。

对于摘要报告,您可以视需要在“摘要显示选项”部分中选中“不显示(公司)”。在这种情况下,该报告会汇总所有(或选定)公司的信息,并且不会单独列出每个选定公司的信息。

应用

要包含在报告中的应用。请选择以下选项之一:

  • 所有应用:包含报告的所有应用。
  • 已选择:显示了一个列表,您可以从中选择要包含在报告中的应用。如果您选择任何应用,报告中会包含所有应用。

此报告会针对每个所选应用显示单独的一行。

对于摘要报告,您可以视需要在“摘要显示选项”部分中选中“不显示(应用)”。在这种情况下,该报告会汇总(或所选的)所有应用的信息,而不会单独列出每个所选应用的信息。

币种

报告所用的货币。有效值包括:

  • 本地货币:报告中的每一行都按照适用的费率方案显示。也就是说,如果开发者的方案使用不同的货币,则一份报告中可能会有多个货币。
  • EUR:此报告中的本地货币交易会换算成欧元(以欧元为单位)。
  • GPB:报告中的本地货币交易会换算成以英镑为单位的交易。
  • 美元:报表中的本地货币交易会换算成美元。
摘要显示选项

对列进行分组和在报告中显示的顺序。选择一个数字,用于表示该分组在分组中的相对顺序(1 表示第一个分组)。例如,下面的先是按软件包、产品、开发者、应用对报告进行分组。

如果您不想显示某个部分,请选择不显示,然后按顺序选择其余字段。当您更改某一部分的相对顺序或选择不在报告中显示某个部分时,该顺序会自动更新。

生成和下载报告

生成报告后,您可以下载 CSV 或 zip 文件格式的报告结果。您可以同步异步生成 CSV 或 zip 文件。

  • 对于同步报告,您运行报告请求,并且在分析服务器提供响应之前,该请求会被阻止。但是,由于报告可能需要处理大量数据(例如 100 GB),同步报告可能会由于超时而失败。

    摘要报表级别仅支持同步生成报表。

  • 对于异步报告,您运行报告请求并在稍后检索结果。适合使用异步查询处理的情况包括:

    • 分析和生成跨越很长时间间隔的报告。
    • 使用各种分组维度以及增加查询复杂性的其他限制条件来分析数据
    • 在发现某些用户或组织的数据量大幅增加时管理查询。

    详细报告级别支持异步生成。

如需生成并下载 CSV 或 zip 格式的报告,请执行以下一项任务:

  1. 访问“报告”页面。
  2. 将光标悬停在要下载的报告上。
  3. 修改列下方,点击以下任一选项:

    1. CSV 文件图标 图标或 ZIP 文件图标 图标(用于摘要报告)。报告会同步保存到 CSV 或 zip 文件中。
    2. 提交作业(针对详细报告)。异步作业会启动。
      1. 修改后的列中监控作业的状态。

        报告可供下载时,系统会显示磁盘图标:

        报告可供下载时,系统会显示磁盘映像。
      2. 作业完成后,点击磁盘图标以下载报告。

下文提供了一个用于摘要结算报告的 CSV 文件示例。

修改报告

要修改报告,请执行以下操作:

  1. 访问“报告”页面
  2. 将光标悬停在要修改的报告上,然后点击操作菜单中的
  3. 根据需要更新报告配置。
  4. 点击更新报告,以保存更新后的报告配置。

删除报告

若要删除报告,请执行以下操作:

  1. 访问“报告”页面
  2. 将光标悬停在要删除的报告上。
  3. 点击操作菜单中的

使用 API 管理创收报告

以下各部分介绍了如何使用该 API 管理创收报告。

使用 API 配置报告

如需为整个组织配置报告,请向 /organizations/{org_name}/report-definitions 发出 POST 请求。

如需为特定开发者配置报告,请向 /organizations/{org_name}/developers/{dev_id}/report-definitions 发出 POST 请求,其中 {dev_id} 是开发者的标识。

发出请求时,您需要指定报表的名称和类型。类型是以下类型之一:BILLINGREVENUEVARIANCE(已弃用)或 PREPAID_BALANCE。此外,您还可以在 mintCriteria 属性中指定条件,以进一步配置报告。您可以指定大量条件,这为您配置报表提供了极大的灵活性。您可以指定以下条件:

  • 对于结算或预付款余额报告,相应报告的结算月份
  • 对于收入报告,报告中包含的交易类型(例如购买交易、收费交易和退款)
  • 对于预付费余额报告,查看该报告的开发者
  • 对于收入报告,报告适用的 API 产品组合(或 API 软件包)、产品、费率方案和应用
  • 对于收入或方差报告,报告的适用币种
  • 对于结算、预付款余额或收入报告,报告是摘要报告还是详细报告
  • 对于收入摘要报告,您可以在报告中包含自定义交易属性

如需查看报告条件的完整列表,请参阅报告配置选项

例如,以下内容创建了一个收入报告,其中汇总了 2015 年 7 月的交易活动。该报告包含 transactionTypes 属性中指定的各种交易类型,专门适用于 Payment API 产品软件包和 Payment API 产品。由于报告定义中未指定特定开发者或应用,因此此报告适用于所有开发者和应用。由于 currencyOption 属性设置为 LOCAL,因此报告中的每一行都会显示使用适用费率方案的币种。此外,groupBy 属性指定将报告中的列按以下顺序分组:PACKAGE、PRODUCT、DEVELOPER、APPLICATION 和 RATEPLAN(包括报告中的费率方案名称和 ID)。

$ curl -H "Content-Type: application/json" -X POST -d \
'{
      "name": "July 2015 revenue report",
      "description": " July 2015 revenue report for Payment product",
      "type": "REVENUE",     
      "mintCriteria":{
         "fromDate":"2015-07-01 00:00:00",
         "toDate":"2015-08-01 13:35:00",
         "showTxDetail":true,
         "showSummary":true,
         "transactionTypes":[
            "PURCHASE",
            "CHARGE",
            "REFUND",
            "CREDIT",
            "SETUPFEES",
            "TERMINATIONFEES",
            "RECURRINGFEES"
         ],
         "monetizationPackageIds":[
            "payment"
         ],
         "productIds":[
            "paymentorg-1@@@payment"
         ],
         "currencyOption":"LOCAL",
         "groupBy":[
            "PACKAGE",
            "PRODUCT",
            "DEVELOPER",
            "APPLICATION",
            "RATEPLAN"
         ]
      }
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions" \
-u email:password

下面给出了一个详细结算报告,其中显示了 2015 年 6 月的开发者 DEV 5 的活动。

$ curl -H "Content-Type:application/json" -X POST -d \
'{
      "name": "June billing report, DEV FIVE",
      "description": "June billing report, DEV FIVE",
      "type": "BILLING",      
      "mintCriteria":{
         "billingMonth": "JUNE",
         "billingYear": 2015,
         "showTxDetail":true,
         "showSummary":false,         
         "currencyOption":"LOCAL"         
      },
      "devCriteria":[{
         "id":"RtHAeZ6LtkSbEH56",
         "orgId":"myorg"}]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xU/report-definitions" \
-u email:password

使用 API 查看报告配置

您可以查看单位的特定报告配置或所有报告配置。您还可以查看个别开发者的报告配置。

要查看组织的特定报告配置,请向 /organizations/{org_name}/report-definitions/{report_definition_id} 发出 GET 请求,其中 {report_definition_id} 是特定报告配置的标识(创建报告配置时,响应中会返回此 ID)。例如:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/1f7fa53b-de5a-431d-9438-62131e1396c5" \
-u email:password

要查看组织的所有报告配置,请向 /organizations/{org_name}/report-definitions 发出 GET 请求。

您可以传递以下查询参数来对结果进行过滤和排序:

查询参数 说明
all 此标记指示是否返回所有 API 产品软件包。如果设置为 false,则每页返回的 API 商品集数量由 size 查询参数定义。默认为 false
size 每页返回的 API 产品软件包数量。默认为 20。如果 all 查询参数设置为 true,则忽略此参数。
page 要返回的页面数量(如果内容已分页)。如果 all 查询参数设置为 true,则忽略此参数。
sort 信息排序所依据的字段。如果 all 查询参数设置为 true,则忽略此参数。默认值为 UPDATED:DESC

例如,以下代码会返回组织的报告配置,并将检索次数限制为最多 5 个报告配置:

$ curl -H "Accept:application/json" -X GET \ 
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions?size=5" \ 
-u email:password

响应应类似如下所示(仅显示部分响应):

{
  "reportDefinition" : [ {
    "description" : "Test revenue report",
    "developer" : null,
    "id" : "1f7fa53b-de5a-431d-9438-62131e1396c5",
    "lastModified" : "2015-08-27 15:44:03",
    "mintCriteria" : {
      "asXorg" : false,
      "currencyOption" : "LOCAL",
      "fromDate" : "2015-07-01 00:00:00",
      "groupBy" : [ "PACKAGE", "PRODUCT", "DEVELOPER", "APPLICATION", "RATEPLAN" ],
      "monetizationPackageIds" : [ "payment" ],
      "productIds" : [ "paymentorg-1@@@payment" ],
      "showRevSharePct" : false,
      "showSummary" : true,
      "showTxDetail" : true,
      "showTxType" : false,
      "toDate" : "2015-08-01 00:05:00",
      "transactionTypes" : [ "PURCHASE", "CHARGE", "REFUND", "CREDIT", "SETUPFEES", "TERMINATIONFEES", "RECURRINGFEES" ]
    },
    "name" : "Test revenue report",
    "organization" : {
      ...
    },
    "type" : "REVENUE"
  }, {
    "description" : "June billing report, DEV FIVE",
    "developer" : null,
    "id" : "fedac696-ce57-469b-b62c-a77b535fd0eb",
    "lastModified" : "2015-08-27 17:13:20",
    "mintCriteria" : {
      "asXorg" : false,
      "billingMonth" : "JUNE",
      "billingYear" : 2015,
      "currencyOption" : "LOCAL",
      "showRevSharePct" : false,
      "showSummary" : false,
      "showTxDetail" : true,
      "showTxType" : false
    },
    "name" : "June billing report, DEV FIVE",
    "organization" : {
      ...
    },
    "type" : "BILLING"
  } ],
  "totalRecords" : 2
}

要查看特定开发者的报告配置,请向 /organizations/{org_name}/developers/{dev_id}/report-definitions 发出 GET 请求,其中 {dev_id} 是开发者的标识。发出请求时,您可以指定上述查询参数,以对数据进行过滤和排序。

例如,以下代码会返回特定开发者的报告配置,并按报告名称对响应进行排序:

$ curl -H "Accept:application/json" -X GET \ 
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xUreport-definitions?sort=name" \ 
-u email:password

使用 API 更新报告配置

如需更新报告配置,请向 /organizations/{org_name}/report-definitions/{report_definition_id} 发出 PUT 请求,其中 {report_definition_id} 是特定报告配置的标识。进行更新时,您需要在请求正文中指定更新后的配置值和报告配置的 ID。例如,以下请求会将报告更新为摘要报告(突出显示了更新后的属性):

$ curl -H "Content-Type: application/json" -X PUT -d \
 '{
       "id": "fedac696-ce57-469b-b62c-a77b535fd0eb",
       "name": "June billing report, DEV FIVE",
       "description": "June billing report, DEV FIVE",
       "type": "BILLING",      
       "mintCriteria":{      
         "billingMonth": "JUNE",
         "billingYear": 2015,
         "showTxDetail":false,
         "showSummary":true    
        }     
 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/fedac696-ce57-469b-b62c-a77b535fd0eb" \
-u email:password

响应应类似如下所示(仅显示部分响应):

{
 "description" : "June billing report, DEV FIVE",
  "developer" : null,
  "id" : "fedac696-ce57-469b-b62c-a77b535fd0eb",
  "lastModified" : "2015-08-27 17:47:29",
  "mintCriteria" : {
    "asXorg" : false,
    "billingMonth" : "JUNE",
    "billingYear" : 2015,
    "showRevSharePct" : false,
    "showSummary" : true,
    "showTxDetail" : false,
    "showTxType" : false
  },
  "name" : "June billing report, DEV FIVE",
  "organization" : {
    ... 
  },
  "type" : "BILLING"
}

使用 API 删除报告配置

如需删除报告配置,请向 /organizations/{org_namer}/report-definitions/{report_definition_id} 发出 DELETE 请求,其中 {report_definition_id} 是要删除的报告配置的标识。例如:

$ curl -H "Accept:application/json" -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions/fedac696-ce57-469b-b62c-a77b535fd0eb" \
-u email:password

使用 API 生成报告

配置报告后,您可以生成逗号分隔值 (CSV) 文件格式的报告,以供查看。

如需生成报告,请向 organizations/{org_id}/{report_type} 发出 POST 请求,其中 {report_type} 用于指定您要生成的报告类型。类型包括:

  • billing-reports
  • revenue-reports
  • prepaid-balance-reports
  • variance-reports
此外,您还可以针对特定开发者生成收入报告,如为开发者生成收入报告中所述。

例如,要生成结算报告,请向 organizations/{org_name}/billing-reports 发出 POST 请求。

在请求正文(对于任何类型的报表)中,为报表指定搜索条件。使用 mintCriteria 属性指定搜索条件。如需了解详情,请参阅条件配置选项

例如,以下请求会根据各种条件(例如,开始日期和结束日期、交易类型)搜索收入报告。

$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \
'{
      "fromDate":"2015-07-01 00:00:00",
      "toDate":"2015-08-01 13:35:00",
      "showTxDetail":true,
      "showSummary":true,                
      "transactionTypes":[
        "PURCHASE",
        "CHARGE",
        "REFUND",
        "CREDIT",
        "SETUPFEES",
        "TERMINATIONFEES",
        "RECURRINGFEES"
      ],
      "currencyOption":"LOCAL",
      "groupBy":[
        "PACKAGE",
        "PRODUCT",
        "DEVELOPER",
        "APPLICATION",
        "RATEPLAN"]
 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/revenue-reports" \
-u email:password

找到之后,系统会以 CSV 文件格式生成收入报告。下面提供了报告输出的一个示例:

Reporting Period:,From:,2015-07-01,  To:,2015-07-31
API Product:,All
Developer:,All
Application:,All
Currency:,Local
Type of Report:,Summary Revenue Report

Monetization Package,Package ID,API Product,Product ID,Developer Name,Developer ID,Application Name,Application ID,Rate Plan,Plan ID,Currency,Transaction Type,Provider Status,Total Volume,Charged Rate,
Location,location,foo_product,foo_product,Apigee,QQ7uxeMGf3w9W08B,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,
Location,location,foo_product,foo_product,BarCompany,barcompany,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,
Location,location,foo_product,foo_product,fremont,fremont,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,
Location,location,foo_product,foo_product,Juan's Taco Shack,juan-s-taco-sha,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,

使用 API 将收入自定义属性包含在收入报告中

(仅限收入报告)如果开发者已定义自定义属性,您可以在报告中添加自定义属性。在将开发者添加到组织时,您可以定义自定义特性,如管理应用开发者中所述。

如需在收入报告中添加自定义特性,请向 organizations/{org_name}/revenue-reports 发出 POST 请求并在请求正文中包含 devCustomAttributes 数组:

"devCustomAttributes": [
    "custom_attribute1",
    "custom_attribute2",
    ...
]

注意:请勿在 devCustomAttributes 数组中指定预定义的 MINT_*ADMIN_* 属性,

例如,以下示例在报告中包含三个自定义属性:BILLING_TYPESFIDORG_EXT(如果开发者已定义):

$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \
'{
      "fromDate":"2015-07-01 00:00:00",
      "toDate":"2015-08-01 13:35:00",
      "showTxDetail":true,
      "showSummary":true,                
      "transactionTypes":[
        "PURCHASE",
        "CHARGE",
        "REFUND",
        "CREDIT",
        "SETUPFEES",
        "TERMINATIONFEES",
        "RECURRINGFEES"
      ],
      "currencyOption":"LOCAL",
      "groupBy":[
        "PACKAGE",
        "PRODUCT",
        "DEVELOPER",
        "APPLICATION",
        "RATEPLAN"
      ],
      "devCustomAttributes": [
         "BILLING_TYPE",
         "SFID",
         "ORG_EXT"
      ]
 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/revenue-reports" \
-u email:password

下面提供了一份报告输出示例,其中包含两个自定义属性的值:

Reporting Period:,From:,2015-07-01,  To:,2015-07-31
API Product:,All
Developer:,All
Application:,All
Currency:,Local
Type of Report:,Summary Revenue Report

Monetization Package,Package ID,API Product,Product ID,Developer Name,Developer ID,Application Name,Application ID,Rate Plan,Plan ID,Currency,Transaction Type,Provider Status,Total Volume,Charged Rate,BILLING_TYPE,SFID,ORG_EXT 
Location,location,foo_product,foo_product,Apigee,QQ7uxeMGf3w9W08B,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,
Location,location,foo_product,foo_product,BarCompany,barcompany,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,
Location,location,foo_product,foo_product,fremont,fremont,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,
Location,location,foo_product,foo_product,Juan's Taco Shack,juan-s-taco-sha,my_app,my_app,rate_plan_1,location_rate_plan_1,USD,SETUPFEES,SUCCESS,1,15.0000,PREPAID,123,3AA,

使用 API 报告交易活动

您可以通过向 /organizations/{org_name}/transaction-search 发出 POST 请求来查看组织的事务活动。发出请求时,您需要指定检索条件。您可以指定以下条件:

  • 签发交易的一个或多个 API 产品的 ID。
  • 交易的月份和年份。
  • 发出交易的开发者。
  • 交易类型,例如 purchase 和 setupfee。
  • 处理记录状态,例如成功和失败。

如需查看完整的条件列表,请参阅条件配置选项

例如,以下命令返回了特定开发者在 2015 年 6 月的结算月份发出的交易:

$ curl -H "Content-Type:application/json" -X POST -d \
 '{        
    "billingMonth": "JUNE",
    "billingYear": 2015,
    "devCriteria": [{
      "id": "RtHAeZ6LtkSbEH56",
      "orgId":"myorg"}],
    "transactionTypes": ["PURCHASE", "CHARGE", "SETUPFEES"],
    "transactionStatus": ["SUCCESS", "FAILED"]
    }'
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/transaction-search \
-u email:password

您还可以确定哪些应用、开发者、API 产品软件包或 API 产品在给定日期范围内发生了交易活动。您需要为每种类型的对象单独查看此信息。例如,您可以查看有关在指定的开始日期和结束日期内访问变现 API 产品软件包中的 API 的应用的具体信息。

如需查看有关事务活动的信息,请向以下资源之一发出 GET 请求:

资源 返回值
/organizations/{org_name}/applications-with-transactions

事务处理应用

/organizations/{org_name}/developers-with-transactions

有交易的开发者

/organizations/{org_name}/products-with-transactions

包含交易的产品

/organizations/{org_name}/packages-with-transactions

包含交易的 API 产品软件包(或 API 软件包)

发出请求时,您需要将日期范围的开始日期和结束日期指定为查询参数。例如,以下请求会返回 2015 年 8 月期间有开发者的开发者。

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers-with-transactions?START_DATE=2015-08-01&END_DATE=2015-08-31" \
-u email:password

响应应类似如下所示(仅显示部分响应):

{
  "developer" : [ {
    "address" : [ {
      "address1" : "Dev Five Address",
      "city" : "Pleasanton",
      "country" : "US",
      "id" : "0917f15f-9521-4e69-9376-07aa7b7b32ca",
      "isPrimary" : true,
      "state" : "CA",
      "zip" : "94588"
    } ],
    "approxTaxRate" : 0.0900,
    "billingType" : "POSTPAID",
    "broker" : false,
    "developerRole" : [ ],
    "email" : "dev5@myorg.com",
    "hasSelfBilling" : false,
    "id" : "tJZG6broTpGGGeLV",
    "legalName" : "DEV FIVE",
    "name" : "Dev Five",
    "organization" : {
      ...
    },
    "registrationId" : "dev5",
    "status" : "ACTIVE",
    "type" : "UNTRUSTED"
  }, {
    "address" : [ {
      "address1" : "Dev Seven Address",
      "city" : "Pleasanton",
      "country" : "US",
      "id" : "f86d8c9f-6ed1-4323-b050-6adf494096c9",
      "isPrimary" : true,
      "state" : "CA",
      "zip" : "94588"
    } ],
    "approxTaxRate" : 0.0900,
    "billingType" : "POSTPAID",
    "broker" : false,
    "developerRole" : [ ],
    "email" : "dev7@myorg.com",
    "hasSelfBilling" : false,
    "id" : "VI3l8m8IPAvJTvjS",
    "legalName" : "DEV SEVEN",
    "name" : "Dev Seven",
    "organization" : {
      ...
    },
    "registrationId" : "dev7",
    "status" : "ACTIVE",
    "type" : "UNTRUSTED"
  }, ...
  ]
}

用于报告 API 的配置选项

此 API 提供以下报告配置选项:

名称 说明 默认 是否必需?
name

报告的名称。

不适用 兼容
description

报告的说明。

不适用
mintCriteria

配置报告的条件。如需了解详情,请参阅条件配置选项

不适用
type

报告的类型。此值可以是以下值之一:

  • BILLING
  • REVENUE
  • VARIANCE
  • PREPAID_BALANCE
不适用 兼容

条件配置选项

通过 mintCriteria 属性可为报告提供以下配置选项:

名称 说明 默认 是否必需?
appCriteria

要包含在报告中的特定应用的 ID 和组织。如果未指定此属性,报告中包含所有应用。

不适用
billingMonth

注意:此属性不适用于收入报告。

报告的结算月份,例如 7 月。

不适用 兼容
billingYear

注意:此属性不适用于收入报告。

报告的结算年份,例如 2015。

不适用 兼容
currCriteria

特定币种的 ID 和组织名称将包含在报告中。如果未指定此属性,报告将包含所有支持的货币。

不适用
currencyOption

报告所用的货币。有效值包括:

  • LOCAL。报告的每一行都使用适用的费率方案显示。这意味着,如果开发者有采用不同币种的方案,同一报告中可能会有多个币种。
  • EUR。本地货币交易换算和显示欧元。
  • GPB。本地货币交易换算和显示英镑。
  • USD。本地货币交易换算成以美元为单位。
不适用
devCriteria

报告中包含特定开发者的开发者 ID(电子邮件地址)和组织名称。如果未指定此属性,报告中包含所有开发者。例如:

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]
                
不适用
devCustomAttributes

注意:此属性仅适用于收入报告。

为报告定义的自定义属性(如果为开发者定义)。例如:

"devCustomAttributes": [
    "custom_attribute1",
    "custom_attribute2",
    ...
]

注意:请勿在 devCustomAttributes 数组中指定预定义的 MINT_*ADMIN_* 属性,

不适用
fromDate

注意:此属性仅适用于收入、差异和交易活动报告。

报告的开始日期(采用世界协调时间/UTC)。

不适用 对于收入报表,是必需的;对于其他类型的报表,则不是必需的。
groupBy

报告中的列分组顺序。有效值包括:

  • APPLICATION
  • BALANCE
  • DEVELOPER
  • ORG
  • PACKAGE
  • PRODUCT
  • RATEPLAN
不适用
monetizationPackageId

要纳入报告的一个或多个 API 产品软件包的 ID。如果未指定此属性,报告中包含所有 API 产品套装。

注意 :此属性在查看交易活动 (/transaction-search) 时无效。

不适用
pkgCriteria

要纳入报告的特定 API 产品软件包的 ID 和组织。如果未指定此属性,报告中包含所有 API 产品软件包。您可以指定此属性,而不是 monetizationpackageIds 属性。

注意 :此属性在查看交易活动 (/transaction-search) 时无效。

不适用
prevFromDate

注意:此属性仅适用于方差报告。

上一时间段的开始日期(采用世界协调时间/UTC)。用于创建与前一个时间段进行比较的报告,以便与当前报告进行比较。

不适用
prevToDate

注意:此属性仅适用于方差报告。

上一时间段在世界协调时间 (UTC) 的结束日期。用于创建与前一个时间段进行比较的报告,以便与当前报告进行比较。

不适用
prodCriteria

要纳入报告的特定 API 产品的 ID 和组织。如果未指定此属性,报告中包含所有 API 产品。您可以指定此属性,而不是 productIds 属性。

注意 :此属性在查看交易活动 (/transaction-search) 时无效。

不适用
productIds

要包含在报告中的一个或多个 API 产品的 ID。如果未指定此属性,报告中包含所有 API 产品。

API 产品 ID 应指定为 org-name@@@product-name。 例如 "productIds": ["myorg@@@myproduct", "myorg@@@myproduct2"]

不适用
pricingTypes

报告中包含的费率方案的定价类型。有效值包括:

  • REVSHARE。收益分成方案。
  • REVSHARE_RATECARD。收益分成和价目表费率方案。
  • RATECARD。价目表方案。

如果未指定此属性,报表中将包含所有价格类型的费率方案。

不适用
ratePlanLevels

报告中要包含的价格方案的类型。有效值包括:

  • DEVELOPER。开发者费率方案。
  • STANDARD。标准费率方案。

如果未指定此属性,报表中会包含开发者专用费率和标准费率方案。

不适用
showRevSharePct

此标记用于指定报告是否显示收益分成百分比。有效值包括:

  • true。显示收益分成百分比。
  • false。不显示收益分成百分比。
不适用
showSummary

用于指定报告是否为摘要的标志。有效值包括:

  • true。报告是摘要。
  • false。报告并不是摘要。
不适用
showTxDetail

注意:此属性仅适用于收入报告。

此标记用于指定报告是否显示交易级详情。有效值包括:

  • true。显示交易级详细信息。
  • false。不显示交易级详情。
不适用
showTxType

此标记用于指定报告是否显示每笔交易的类型。有效值包括:

  • true:显示每笔交易的类型。
  • false。请勿显示每笔交易的类型。
不适用
toDate

注意:此属性仅适用于收入、差异和交易活动报告。

报告的结束日期(采用世界协调时间)。

该报告包含指定日期结束之前收集的数据。 从报告中指定的结束日期收集的报告数据将从报告中排除。 例如,如果您想在 2016 年 12 月 31 日过期某个费率方案,则应将 toDate 值设为 2017-01-01。 在这种情况下,报告将包含截至 2016 年 12 月 31 日当天的报告数据;2017 年 1 月 1 日的报告数据将被排除。

不适用 对于收入报表,是必需的;对于其他类型的报表,则不是必需的。
transactionStatus

要纳入报告的交易状态。有效值包括:

  • SUCCESS。交易成功。
  • DUPLICATE。重复的翻译。这些事务可以忽略。从 Apigee 运行时到评分服务器的数据流水线有时可能会生成重复事务,以便能够容错,并且创收功能会对其进行识别并将其标记为重复。
  • FAILED。交易失败。当前提条件的验证失败时,就会触发此状态。例如:
    • 即使开发者尚未购买费率方案,也会尝试进行分级。如果未配置创收限制检查政策,就可能会发生这种情况。
    • 已超出配额,但通话仍会继续。如果未配置创收限制检查政策,就可能会发生这种情况。
    • 针对基于特性的自定义方案发送了排除的自定义属性值。
  • INVALID_TSC。交易无效。当 txProviderStatus 运行时条件与 API 产品软件包级别指定的成功条件不匹配时,会触发此状态。
  • REVIEW。需要审核的交易。如果值位于未配置的收入范围内,则针对灵活收益分成方案触发此状态。
不适用
transactionCustomAttributes

要包含在摘要收入报告中的自定义交易属性。您必须在组织中启用此功能。请参阅在收入摘要报告中添加自定义交易属性

不适用
transactionTypes

报告中包含的交易类型。有效值包括:

如果未指定此属性,报告中包含所有交易类型。

不适用