管理報表

您目前查看的是 Apigee Edge 說明文件。
參閱 Apigee X說明文件
資訊

簡介

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

營利報表類型

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

報表 說明
帳單 查看單一帳單月份的開發人員活動,確認費率方案已正確套用。
預付餘額 查看預付開發人員在某個帳單月份或目前結算月份內產生的餘額,方便您核對從付款處理方收到的款項。
收益 查看開發人員在特定日期範圍內產生的活動和收益,以便您分析 API 產品套裝組合和產品對開發人員 (及其應用程式) 的成效。
變異

在兩個日期範圍內比較開發人員產生的活動和收益,即可分析 API 套件、產品與開發人員 (及自家應用程式) 成效的向上或向下趨勢。

關於資料保留

在 Apigee Edge 公有雲中,營利資料保留是一項方案授權。如要查看營利授權,請前往 https://cloud.google.com/apigee/specsheets。如想在授權期結束後保留營利資料,請與 Apigee 銷售人員聯絡。延長資料保留時間會在提出要求時啟用,且無法回溯啟用,以便納入比原始資料保留期更早的資料。

關於重複交易

比較營利交易報表與 Analytics (分析) 資料時,您可能會發現有少量的重複交易。這是預期的行為,因為營利系統每天可以處理好幾百萬筆交易,並在任何特定時刻同時處理多筆交易。平均而言,約有 0.1% 的交易可能重複。

探索「營利報表」頁面

存取「營利報表」頁面,方法如下:

邊緣

如何使用 Edge UI 存取「報表」頁面:

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

「報表」頁面隨即顯示。

如圖所示,您可以在「報表」頁面上執行下列操作:

傳統版 Edge (Private Cloud)

如何使用傳統版 Edge UI 存取「報表」頁面:

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

「報表」頁面隨即顯示。

設定報表

按照下列各節的說明,透過 UI 設定報表。

報表設定步驟

使用 Edge UI 或傳統版 Edge UI 設定報表。

Edge

如何使用 Edge UI 設定報表:

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

    • 按一下「Save as CSV」或「Save as Zip」,以逗號分隔值 (CSV) 或含有 CSV 的壓縮 ZIP 檔案的形式,將產生的報表下載到本機電腦。對大型報表而言,建議使用 ZIP 下載功能,這麼做可提升下載效率。

傳統版 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 產品會自成一行。

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

公司

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

如需摘要報表,您可以視需要勾選「Summary Display Options」區段中的「Do not display」。在這種情況下,報表會匯總所有 (或所選) 公司的資訊,但不會分別列出每間所選公司的資訊。

應用程式

選取要納入報表的應用程式。如未選取,報告就會包含所有申請資料。

在這份報表中,每個所選應用程式都會自成一行。

如需摘要報表,您可以視需要勾選「Summary Display Options」區段中的「Do not display」。在這種情況下,報表會匯總所有 (或所選) 應用程式的資訊,且不會分別列出每個所選應用程式的資訊。

摘要顯示選項

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

如果您不想顯示某個部分,請選取「Do not display」,然後依序選取其餘欄位。當您變更一個區段的相對順序,或選擇不在報表中顯示任何區段時,這個順序會自動更新。

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

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

使用這項功能之前,請務必先審慎規劃及規劃,因此請詳閱下列注意事項。

如果您是雲端客戶,請與 Apigee Edge 支援聯絡以設定屬性。如果您是適用於 Private Cloud 客戶的 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 組成。這應是產品中所有交易記錄政策中的名稱和位置,才能納入報表。

啟用這項功能後,如要在摘要收益報表中加入自訂屬性,請在 MintCriteria 中加入 transactionCustomAttributes,即可使用報表 API。請參閱「條件設定選項」一節。

設定變異數報表 (已淘汰)

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

欄位 說明
日期範圍

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

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

要納入報表的 API 套件。請在下方選取一個適用選項:

  • 全部:包含報表中的所有 API 套件。
  • 已選取:顯示可選取要納入報表的 API 套件清單。如未選取套件,報表會納入所有套件。

報表中會為每個 API 套件自成一行。

如需摘要報表,您可以視需要勾選「Summary Display Options」專區中的「Don't Display (Packages)」。在這種情況下,報表會匯總所有 (或所選) API 套件的資訊,但不會分別列出每個 API 套件的資訊。

產品

要加進報表的 API 產品。請在下方選取一個適用選項:

  • 全部:包含報表中的所有 API 產品。
  • 已選取:顯示可選取要納入報表的產品清單。如果未選取任何產品,報表會納入所有產品。

報表中的每項 API 產品會自成一行。

如需摘要報表,您可以視需要勾選「Summary 顯示選項」專區中的「不顯示 (產品)」。在這種情況下,報表會匯總所有 (或所選) API 產品的資訊,但不會分別列出各項 API 產品的資訊。

公司

要納入報表的公司。請在下方選取一個適用選項:

  • 全部:包含報表中的所有公司。
  • 已選取:顯示可選取要納入報表的公司清單。如果您選取沒有任何公司,報表會納入所有公司。

在這份報表中,每家選擇的公司會自成一行。

如需摘要報表,您可以視需要勾選「Summary 顯示選項」專區中的「不要顯示 (公司)」。在這種情況下,報表會匯總所有 (或所選) 公司的資訊,但不會分別列出每間所選公司的資訊。

應用程式

要納入報表的應用程式。請在下方選取一個適用選項:

  • 全部:包括報表中的所有應用程式。
  • 已選取:顯示可選取要納入報表的應用程式清單。如果您選取任何應用程式,報告都會納入所有應用程式。

在這份報表中,每個所選應用程式都會自成一行。

如需摘要報告,您可以視需要勾選「Summary 顯示選項」專區中的「不顯示 (應用程式)」。在這種情況下,報表會匯總所有 (或所選) 應用程式的資訊,且不會分別列出每個所選應用程式的資訊。

幣別

報表幣別。有效值包括:

  • 當地幣別:報表中的每一行資料都會以適用的費率方案顯示。也就是說,如果開發人員的方案使用不同的貨幣,則一份報表可能有多種貨幣。
  • 歐元:在報表中換算為當地貨幣的交易,並以歐元顯示。
  • GPB:報表中的當地貨幣交易資料會以英鎊顯示。
  • 美元:報表中的當地貨幣交易金額會以美元顯示。
摘要顯示選項

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

如果您不想顯示某個部分,請選取「Do not display」,然後依序選取其餘欄位。當您變更一個區段的相對順序,或選擇不在報表中顯示任何區段時,這個順序會自動更新。

產生及下載報表

建立報表後,您可以將報表結果下載為 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":[
            "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 要求。

您可以傳遞下列查詢參數,來篩選及排序結果:

查詢參數 說明
all 此標記用於指定是否要傳回所有 API 產品套裝組合。如果設為 false,系統就會由 size 查詢參數定義每頁傳回的 API 產品組合數量。預設值為 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} 是開發人員的身分識別資訊。提出要求時,您可以指定上述查詢參數,來篩選及排序資料。

舉例來說,下列程式碼會傳回特定開發人員的報表設定,並依據報表名稱排序回應:

$ 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。
  • 交易的月份和年份。
  • 核發交易的開發人員。
  • 交易類型,例如購買和設定費用。
  • 交易狀態,例如成功和失敗。

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

舉例來說,以下程式碼會傳回特定開發人員在 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

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

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

不適用