管理報表

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。

簡介

營利報表可讓您存取聚焦用量資訊和交易活動。舉例來說，您可以判斷哪些應用程式、開發人員、API 產品套件或 API 產品在指定日期範圍內有交易活動。您可以利用營利功能，產生可追蹤 API 用量的摘要或詳細報表。

營利報告類型

您可以產生以下類型的營利報表。

關於資料保留

在 Apigee Edge 公有雲中，營利資料保留是一項方案授權。請前往 https://cloud.google.com/apigee/specsheets 查看營利授權。如想在授權效期內保留營利資料，請與 Apigee 銷售人員聯絡。系統會在要求時啟用額外資料保留功能，且無法溯及既往的資料啟用之前，無法溯及既往。

探索營利報表頁面

使用「營利」頁面 (說明如下)。

設定報表

依照使用者介面的說明設定報表，如以下各節所述。

設定報表的步驟

使用 Edge UI 或 Classice Edge UI 設定報告。

設定帳單報表

按照設定報表的步驟並在報表頁面中輸入下列資訊：

設定預付餘額報表

設定收益報表

按照設定報表的步驟並在報表頁面中輸入下列資訊：

在收益摘要報表中納入自訂交易屬性

交易記錄政策可讓您擷取交易中的自訂屬性資料，而您可以在自訂收益報表中加入這些自訂屬性。為貴機構設定 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_id 和 tax_source 欄新增至營利資料庫。請注意，API 呼叫中的自訂屬性陣列會採用網址編碼。

在報表中納入自訂交易屬性的注意事項

• 透過 API 建立屬性前，請務必先確定要使用的屬性名稱。這些是資料庫中的資料欄名稱，自訂屬性資料一律會儲存在此處。
• 每筆交易記錄政策中都有 10 個可用的自訂屬性運算單元，如下圖所示。請針對要納進報表的產品，為相同的屬性使用相同的屬性名稱和位置。舉例來說，在下列交易記錄政策中，partner_id 和 tax_source 自訂屬性分別位於方塊 4 和 5。這個名稱應為所有交易記錄政策的名稱和位置，才能納入報表。
  
  

如要在啟用此功能後，在摘要收益報表中加入自訂屬性，請在 MintCriteria 中加入 transactionCustomAttributes。請參閱「條件設定選項」。

設定變化版本報表 (已淘汰)

按照設定報表的步驟並在報表頁面中輸入下列資訊：

產生及下載報表

建立報表後，您可以下載 CSV 或 ZIP 檔案格式的報表結果。 您可以同步或以非同步方式產生 CSV 或 ZIP 檔案。

• 同步報表：您執行了報表要求，且在分析伺服器提供回應之前，要求就會遭到封鎖。不過，由於報表可能需要處理大量資料 (例如 100 的 GB)，因此同步報告可能會因為逾時而失敗。

  摘要報表層級僅支援同步產生。

• 非同步報表：您之後必須執行報表報表並擷取結果。在某些情況下，非同步查詢處理可能是不錯的替代方案：

  • 分析及建立涵蓋不同時間範圍的報表。
  • 使用各種群組維度和其他限制分析資料，提高查詢的複雜度。
  • 如果發現部分使用者或機構的資料量大幅增加，即可管理查詢作業。

  詳細報表層級支援非同步產生。

如要產生 CSV 或 ZIP 檔案格式的報表，請執行以下其中一項工作：

1. 前往「報表」頁面。
2. 將滑鼠遊標移至您要下載的報表上。

3. 在「修改」欄下方，點選任一選項：

   1. 圖示或 圖示 (適用於摘要報表)。系統會將報表以 CSV 或 ZIP 檔案格式同步儲存。
   2. 提交工作 (詳細報表)。非同步工作會啟動。

      1. 在「Modified」欄中監控工作狀態。

         報表可供下載時，畫面上會顯示磁碟圖示：

         
      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":[
            "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

下列建立後的詳細帳單報表將顯示開發人員 DEV Fence 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 要求。

您可以傳遞下列查詢參數，篩選及排序結果：

舉例來說，會傳回下列機構的報表設定，並限制擷取作業上限為五項報表設定：

$ 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_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",
    ...
]