管理報表

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

簡介

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

營利報告類型

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

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

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

關於資料保留

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

探索營利報表頁面

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

邊緣

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

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

「報表」頁面隨即顯示。

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

傳統版 Edge (私有雲)

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

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

「報表」頁面隨即顯示。

設定報表

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

設定報表的步驟

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

邊緣

如何使用 Edge UI 設定報告:

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

    • 按一下 [另存為 CSV] 或 [另存新檔],將產生的報表以逗號分隔值 (CSV) 格式下載,或是下載到 CSV 檔案的 ZIP 壓縮檔。我們建議大型報表下載 ZIP 檔案,進而提升下載速度。

傳統版 Edge (私有雲)

使用傳統版 Edge UI 建立報表的步驟如下:

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

    • 按一下「Download CSV」(下載 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 私有客戶,請使用具備系統管理員憑證的 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 套件中的資訊 (且不會單獨列出每個 API 套件的資訊)。

產品

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

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

每份所選 API 產品都會自成一行。

如需摘要報表,您可以視需要在「摘要顯示選項」部分勾選「不要顯示 (產品)」。在這種情況下,報表匯總了所有 (或所選) API 產品的資訊 (不會單獨列出每個 API 產品的資訊)。

公司

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

  • 全部:在報表中納入所有公司。
  • 已選取:顯示清單,方便您選取要納入報表的公司。如果您選取任何公司,報表就會納入所有公司。

報表會把每個公司都自成一行。

對於摘要報表,您可以視需要勾選「摘要顯示選項」部分中的「不要顯示 (公司)」。在這種情況下,報表會匯總所有 (或特定) 公司的相關資訊 (不會單獨列出每間選取公司的資訊)。

應用程式廣告活動

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

  • 全部:包含報表中的所有應用程式。
  • 已選取:顯示清單,讓您選取要納入報表的應用程式。如未選取任何應用程式,報表就會納入所有應用程式。

每份所選應用程式都會自成一行。

對於摘要報表,您可以視需要勾選「摘要顯示選項」部分中的「不要顯示 (應用程式)」。在這種情況下,報表匯總了所有 (或所選) 應用程式的資訊 (不會單獨列出各個所選應用程式的資訊)。

幣別

報表貨幣。有效值包括:

  • 當地幣別:報表中的每一行都會顯示適用的費率方案。也就是說,如果開發人員有使用不同貨幣的企劃書,一種報表可能會有多個貨幣。
  • EUR:報表中的當地貨幣交易會換算成美元,
  • GPB:報表中的當地貨幣交易會換算成英鎊,並以英鎊顯示。
  • USD:報表中的當地貨幣交易會換算成美元,以美元顯示。
摘要顯示選項

欄的分組和顯示順序。選取數字表示分組中相對區段的順序 (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} 為開發人員識別資訊。

提出要求時,您必須指定報表的名稱和類型。屬於以下類型: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

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

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

查詢參數 說明
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" : [ "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。
  • 交易的帳單月份和年份。
  • 核發交易的開發人員。
  • 交易類型,例如購買和設定費用。
  • 交易成功狀態,例如成功和失敗。

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

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

注意:這項資源不適用於收益報表。

報表的帳單月份,例如 JULY。

billingYear

注意:這項資源不適用於收益報表。

報表的帳單年度,例如 2015 年。

currCriteria

報表中顯示的特定貨幣 ID 和機構組織。如未指定這項屬性,報表就會納入所有支援的貨幣。

currencyOption

報表貨幣。有效值包括:

  • LOCAL。報表每一行都會顯示適用的費率方案。也就是說,如果開發人員有使用不同貨幣的方案,一份報表可能會有多個貨幣。
  • EUR。當地幣別交易是以美元為單位進行轉換並顯示。
  • GPB。當地幣別交易是以英國標準幣別換算並顯示。
  • USD。當地幣別交易金額是以美元為單位進行換算。
devCriteria

開發人員 ID 必須納入報表的特定開發人員 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

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

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