管理报告

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

简介

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

创收报告的类型

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

数据保留简介

在 Apigee Edge 公有云中，创收数据保留是一项方案权限。如需了解创收权益，请访问 https://cloud.google.com/apigee/specsheets。如果您想在订阅期结束后继续保留创收数据，请与 Apigee 销售团队联系。延长数据保留期在请求时启用，并且无法追溯启用以包含早于原始数据保留期的数据。

关于重复交易

如果您将创收交易报告与 Google Analytics（分析）数据进行比较，可能会发现少量重复交易。这属于正常现象，因为创收系统每天可以处理数百万笔交易，同时许多交易会在任意指定时刻并行处理。平均而言，大约 0.1% 的交易可能是重复的。

探索“创收报告”页面

访问“创收报告”页面（如下所述）。

配置报告

按照以下部分所述，使用界面配置报告。

配置报告的步骤

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

配置结算报告

按照步骤配置报告，并在报告页面中输入以下信息：

配置预付款余额报告

配置收入报告

按照步骤配置报告，并在报告页面中输入以下信息：

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

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

使用该功能需要一些考虑和计划，因此请查看以下注意事项。

如果您是云客户，请与 Apigee Edge 支持团队联系以设置该属性。如果您是适用于私有云的 Apigee Edge 客户，请使用系统管理员凭据对以下 API 使用 PUT 请求设置该标志。

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_id 和 tax_source 列添加到获利数据库。请注意，API 调用中的自定义属性数组已进行网址编码。

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

• 在使用 API 创建属性名称之前，请先确定要使用的属性名称。这些是数据库中的列名称，自定义属性数据始终存储在其中。
• 每项交易记录政策中有 10 个可用的自定义属性槽位，如下图所示。对于将要添加到报告中的相同属性，请为各个属性使用完全相同的属性名称和位置。例如，在以下交易记录政策中，partner_id 和 tax_source 自定义属性分别占据方框 4 和 5。对于要包含在报告中的产品，此名称及其在所有交易记录政策中的位置和位置。
  
  

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

配置差异报告（已弃用）

按照步骤配置报告，并在报告页面中输入以下信息：

生成并下载报告

创建报告后，您即可以 CSV 或 ZIP 文件格式下载报告结果。 您可以同步或异步生成 CSV 或 ZIP 文件。

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

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

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

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

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

要生成和下载 CSV 或 zip 文件格式的报告，请执行以下任务之一：

1. 访问“报告”页面。
2. 将光标悬停在要下载的报告上。

3. 在修改时间列下，点击以下任一选项：

   1. 图标或 图标（对于摘要报告）。报告会同步保存到 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} 是开发者的标识。

在发出请求时，您需要指定报告的名称和类型。该类型是以下类型之一：BILLING、REVENUE、VARIANCE（已弃用）或 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":[
            "payment"
         ],
         "currencyOption":"LOCAL",
         "groupBy":[
            "PACKAGE",
            "PRODUCT",
            "DEVELOPER",
            "APPLICATION",
            "RATEPLAN"
         ]
      }
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/report-definitions" \
-u email:password

下面将创建一份详细的结算报告，其中显示开发者 DEV FIVE 在 2015 年 6 月的活动。

$ 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 请求。

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

例如，以下命令会返回组织的报告配置，并将检索的报告配置限制为最多 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" : [ "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_TYPE、SFID 和 ORG_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。
• 交易的结算月份和年份。
• 发起交易的开发者。
• 交易类型，例如购买费和设置费。
• 交易状态，例如成功和失败。

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

例如，以下代码会返回特定开发者在结算月份（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 请求：

发出请求时，您需要指定日期范围的开始日期和结束日期作为查询参数。例如，以下请求会返回在 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 使用：

条件配置选项

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

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]
                

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