管理報表

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

簡介

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

營利報表類型

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

檢舉 說明
帳單 查看開發人員在單一帳單月份的活動,並確認已正確套用費率方案。
預付餘額 查看預付開發人員在帳單月份或目前開放月份的餘額補充金額,以便與付款處理服務供應商收到的款項進行對帳。
收益 查看開發人員在指定日期範圍內產生的活動和收益,以便分析各開發人員 (及其應用程式) 的 API 產品組合和產品成效。
變異

比較開發人員在兩個日期範圍內產生的活動和收益,以便分析各開發人員 (及其應用程式) 的 API 套件和產品成效呈現上升或下降趨勢。

關於資料保留

在 Apigee Edge 公用雲中,營利資料保留期限是方案授權。如要查看營利權限,請前往 https://cloud.google.com/apigee/specsheets。如果您希望營利資料保留超過授權期限,請與 Apigee 銷售團隊聯絡。延長資料保留期限會在要求時啟用,且無法回溯啟用,以便納入原始資料保留期間之前的資料。

關於重複交易

比較營利交易報表和 Analytics 資料時,您可能會發現少數重複交易。這是預期的行為,因為營利系統每天可處理數百萬筆交易,且在任何特定時刻都會並行處理許多交易。平均而言,約 0.1% 的交易可能為重複交易。

探索「營利報表」頁面

請按照下方說明存取「營利報表」頁面。

Edge

如要使用 Edge UI 存取「報表」頁面,請按照下列步驟操作:

  1. 登入 apigee.com/edge
  2. 在左側導覽列中,依序選取「發布」>「營利」>「報表」

畫面上會顯示「報表」頁面。

如圖所示,「報表」頁面可讓您:

Classic Edge (Private Cloud)

如要使用 Edge 傳統版 UI 存取「報表」頁面,請按照下列步驟操作:

  1. 登入 http://ms-ip:9000,其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
  2. 依序選取頂端導覽列中的「營利」>「營利報表」

畫面上會顯示「報表」頁面。

設定報表

如以下節所述,請使用 UI 設定報表。

設定報表的步驟

使用 Edge UI 或 Classic Edge UI 設定報表。

Edge

如要使用 Edge UI 設定報表,請按照下列步驟操作:

  1. 在左側導覽列中,依序選取「發布」>「營利」>「報表」
  2. 按一下「+ 檢舉」
  3. 設定下表中定義的報表詳細資料。
    欄位 說明
    名稱 報表的專屬名稱。
    說明 報告說明。
    報告類型 請參閱「營利報表類型」。
  4. 根據所選報表類型設定其他報表詳細資料,如以下各節所述:
  5. 在報表視窗中輸入資訊後,您可以執行下列操作:
    • 按一下「儲存報表」,即可儲存報表設定。
    • 如要使用詳細報表,請按一下「提交工作」,以非同步方式執行報表,並稍後擷取結果。詳情請參閱「產生及下載報表」。

    • 按一下「Save as CSV」或「Save as Zip」,即可將產生的報表下載到本機,做為半形逗號分隔值 (CSV) 或內含 CSV 的壓縮 ZIP 檔案。建議針對大型報表下載 ZIP 檔案,這樣下載效率會更高。

Classic Edge (Private Cloud)

如要使用 Edge 傳統版 UI 建立報表,請按照下列步驟操作:

  1. 依序選取頂端導覽列中的「營利」>「營利報表」
  2. 在下拉式選單中,選取要建立的報表類型。請參閱「營利報表類型」。
  3. 按一下「+ 檢舉」
  4. 根據所選的結帳類型設定報表詳細資料,如以下各節所述:
  5. 在報表視窗中輸入資訊後,您可以執行下列操作:
    • 按一下「另存新檔」即可儲存報表設定,並稍後下載報表。
    • 如要查看詳細報表,請按一下「提交工作」,即可非同步執行報表並稍後擷取結果。詳情請參閱「產生及下載報表」。

    • 按一下「下載 CSV」,即可產生報表並下載至本機,以半形逗號分隔值 (CSV) 檔案格式供查看。

設定帳單報表

請按照設定報表的步驟操作,並在報表頁面中輸入下列資訊:

欄位 說明
帳單月份

報表的帳單月份。

報表層級

報表層級。有效值包括:

  • 詳細:每筆交易會顯示在個別的資料行中,方便您確認費率方案是否已正確套用。沒有摘要。
  • 摘要:匯總每個 API 產品和開發人員的總收益。
產品組合

注意:在 Edge 傳統版 UI 中,API 產品套裝組合稱為 API 套件。

選取要納入報表的 API 產品組合。如果未選取任何項目,報表會納入所有 API 產品組合。

報表會針對每個所選 API 產品套件加入一行。

如要產生摘要報表,您可以選擇在「摘要」顯示選項中勾選「不顯示」。在這種情況下,報表會匯總所有 (或所選) API 產品套件的資訊 (不會個別列出每個 API 產品套件的資訊)。

產品

選取要納入報表的 API 產品。如果未選取任何產品,報表會納入所有 API 產品。

報表會針對每個所選 API 產品加入一行。

如要產生摘要報表,您可以選擇在「摘要」顯示選項中勾選「不顯示」。在這種情況下,報表會匯總所有 (或所選) 開發人員的資訊 (不會個別列出每位所選開發人員的資訊)。

公司

選取要納入報表的公司。如果未選取任何項目,報表會納入所有公司。

房價方案

要納入報表的費率方案。請在下方選取一個適用選項:

  • 所有費率方案:在報表中納入所有費率方案。
  • 標準費率方案:報表中只包含標準費率方案。
  • 開發人員專用費率方案:報表中只包含開發人員方案。

設定預付餘額報表

請按照設定報表的步驟操作,並在報表頁面中輸入下列資訊:

欄位 說明
帳單月份

報表的帳單月份。

報表層級

報表層級。有效值包括:

  • 詳細:分別顯示每個餘額補充金額,並讓您與付款處理方收到的款項進行對帳。
  • 摘要:摘要列出每位開發人員的總餘額補充金額。
公司

選取要納入報表的公司。如果未選取任何項目,報表中就會納入所有公司。

設定收益報表

請按照設定報表的步驟操作,並在報表頁面中輸入下列資訊:

欄位 說明
日期範圍

報表的日期範圍。請在下方選取一個適用選項:

  • 預設:從下拉式選單中選取任一標準日期範圍 (例如上個月)。
  • 自訂:在日曆彈出式視窗中,選擇範圍的開始日期和結束日期。
選取貨幣

報表的幣別。有效值包括:

  • 當地幣別:報表的每個資料列都會以適用的費率方案顯示。 也就是說,如果開發人員的方案使用不同的幣別,一則報表中可能就會出現多種幣別。
  • 歐元:報表中的當地幣別交易會轉換為歐元並顯示。
  • 英國英鎊:報表中的當地幣別交易會轉換為英鎊並顯示。
  • 美元:報表中的當地幣別交易會轉換為美元並顯示。
報表層級

報表層級。有效值包括:

  • 詳細:每筆交易會顯示在個別的資料行中。沒有摘要。
  • 摘要:根據您選取的參數,列出每項 API 產品和開發人員的總收益。
產品組合

注意:在 Edge 傳統版 UI 中,API 產品套裝組合稱為 API 套件。

選取要納入報表的 API 產品組合。如果未選取任何項目,報表會納入所有 API 產品組合。

報表會針對每個所選 API 產品套件加入一行。

如要產生摘要報表,您可以選擇在「摘要」顯示選項中勾選「不顯示」。在這種情況下,報表會匯總所有 (或所選) API 產品套件的資訊 (不會個別列出每個 API 產品套件的資訊)。

產品

選取要納入報表的 API 產品。如果未選取任何產品,報表會納入所有 API 產品。

報表會針對每個所選 API 產品加入一行。

如要產生摘要報表,您可以選擇在「摘要」顯示選項中勾選「不顯示」。在這種情況下,報表會匯總所有 (或所選) 開發人員的資訊 (不會個別列出每位所選開發人員的資訊)。

公司

選取要納入報表的公司。如果未選取任何項目,報表會納入所有公司。

如要產生摘要報表,您可以選擇在「摘要顯示選項」部分勾選「不顯示」。在這種情況下,報表會匯總所有 (或所選) 公司的資訊,但不會個別列出每家所選公司的資訊。

應用程式

選取要納入報表的應用程式。如果未選取任何項目,報表就會納入所有應用程式。

報表中會為每個所選應用程式列出獨立的資料列。

如要產生摘要報表,您可以選擇在「摘要顯示選項」部分勾選「不顯示」。在這種情況下,報表會匯總所有 (或所選) 應用程式的資訊 (不會個別列出每個所選應用程式的資訊)。

摘要顯示選項

資料欄在報表中分組及顯示的順序。選取一個數字,表示該部分在分組中的相對順序 (1 是第一個分組)。舉例來說,下列報表會先依套件分組,再依產品、開發人員和應用程式分組。

如果不想顯示某個部分,請選取「不顯示」,然後依序選取剩餘的欄位。當您變更某個部分的相對順序,或選擇不顯示報表中的某個部分時,順序會自動更新。

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

交易記錄政策可讓您擷取交易的自訂屬性資料,並在收益摘要報表中納入這些自訂屬性。為貴機構設定 MINT.SUMMARY_CUSTOM_ATTRIBUTES 屬性,藉此定義營利資料庫資料表中包含的預設自訂屬性組合。

使用這項功能時,請先考量以下事項。

如果您是雲端客戶,請與 Apigee Edge 支援團隊聯絡,設定屬性。如果您是 Apigee Edge for Private Cloud 客戶,請使用系統管理員憑證,向下列 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_idtax_source 欄新增至營利資料庫。請注意,API 呼叫中的自訂屬性陣列經過網址編碼。

在報表中加入自訂交易屬性時的考量事項

  • 請先確定要使用的屬性名稱,再使用 API 建立這些屬性。 這些是資料庫中的資料欄名稱,自訂屬性資料一律會儲存在這裡。
  • 每個交易記錄政策都有 10 個可用的自訂屬性插槽,如下圖所示。請為報表中納入的產品使用相同的屬性,使用完全相同的屬性名稱和位置。舉例來說,在下列交易記錄政策中,partner_idtax_source 自訂屬性分別佔用方塊 4 和 5。這是所有產品記錄交易政策中的名稱和職位,必須納入報表。

如要在啟用這項功能後,在收益摘要報表中加入自訂屬性,請使用報表 API,將 transactionCustomAttributes 新增至 MintCriteria。請參閱「評估準則設定選項」。

設定差異報表 (已淘汰)

請按照設定報表的步驟操作,並在報表頁面中輸入下列資訊:

欄位 說明
日期範圍

報表的日期範圍。請在下方選取一個適用選項:

  • 預設:從下拉式選單中選取任一標準日期範圍 (例如上個月)。
  • 自訂:在日曆彈出式視窗中,選擇範圍的開始日期和結束日期。
套件

要納入報表的 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. 在「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} 是開發人員的 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":[
            "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 (您建立報表設定時,系統會在回應中傳回 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

舉例來說,以下指令會傳回機構的報表設定,並將擷取數量限制為最多五個報表設定:

$ 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} 是開發人員的 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。更新時,您需要在要求主體中指定更新的設定值和報表設定 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} 是所要刪除的報表設定 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。
  • 交易的帳單月份和年份。
  • 發出交易的開發人員。
  • 交易類型,例如購買和設定費。
  • 交易狀態,例如成功和失敗。

如需完整的條件清單,請參閱「條件設定選項」。

舉例來說,下列指令會傳回特定開發人員在 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

注意:此屬性僅適用於收益、差異和交易活動報表。

報表的開始日期 (以世界標準時間為準)。

不適用 收益報表必須提供這個資訊,其他報表類型則不必提供。
groupBy

報表中資料欄分組的順序。有效值包括:

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

要納入報表的一或多個 API 產品套件的 ID。如果未指定這個屬性,報表就會納入所有 API 產品組合。

注意: 查看交易活動 (/transaction-search) 時,這個屬性無效。

不適用
pkgCriteria

要納入報表的特定 API 產品組合 ID 和組織。如果未指定這個屬性,報表就會納入所有 API 產品組合。您可以指定這個屬性,而非 monetizationpackageIds 屬性。

注意: 查看交易活動 (/transaction-search) 時,這個屬性無效。

不適用
prevFromDate

注意:這個屬性僅適用於差異報表。

上一個期間的開始日期 (世界標準時間)。用於建立先前期間的報表,以便與目前的報表進行比較。

不適用
prevToDate

注意:這個屬性僅適用於差異報表。

上一個期間的結束日期 (世界標準時間)。用於建立先前期間的報表,以便與目前的報表進行比較。

不適用
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

報表中要納入的交易類型。有效值包括:

如果未指定這個屬性,報表就會包含所有交易類型。

不適用