管理報表

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

簡介

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

營利報表類型

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

報表 說明
帳單 查看開發人員在單一帳單月內的活動,並驗證費率方案是否已正確套用。
預付餘額 查看預付型開發人員在帳單月份或目前開戶月份的餘額補充餘額,以便與付款處理方收到的款項進行對帳。
收益 查看開發人員在特定日期範圍內產生的活動和收益,以便分析您的 API 產品組合和開發人員 (及其應用程式) 的產品成效。
變異

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

關於資料保留

在 Apigee Edge 公有雲中,營利資料保留是一項方案授權。如要查看營利授權,請前往 https://cloud.google.com/apigee/specsheets。如果希望在授權期結束後保留營利資料,請與 Apigee 銷售團隊聯絡。擴充資料保留功能會在提出要求時啟用,而且無法溯及既往納入早於原始資料保留期限的資料。

探索營利報表頁面

按照下文說明前往「營利報表」頁面。

邊緣

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

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

系統隨即會顯示「報表」頁面。

如圖中所示,您可以透過「報表」頁面執行以下動作:

傳統邊緣 (Private Cloud)

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

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

系統隨即會顯示「報表」頁面。

設定報表

請按照下列各節說明,透過使用者介面設定報表。

設定報表的步驟

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

Edge

如何使用 Edge UI 設定報表:

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

    • 按一下「Save as CSV」或「Save as Zip」,將產生的報表下載為逗號分隔值 (CSV) 或包含 CSV 的壓縮檔。建議您下載 ZIP 檔案供大型報表使用,且下載作業會比以往更有效率。

傳統邊緣 (Private Cloud)

如何使用傳統版 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 產品。

報表會為您選取的每個 API 產品單獨列出一行。

針對摘要報表,您可以視需要在「摘要顯示」選項中勾選「不要顯示」。在此情況下,報表會匯總所有 (或已選取) 開發人員的資訊,而且不會分別列出每個所選開發人員的資訊。

公司

選取要納入報表的公司。如未選取,報表就會納入所有公司。

房價方案

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

  • 所有房價方案:在報表中加入所有房價方案。
  • 標準費率方案:在報表中僅包含標準費率方案。
  • 開發人員專屬費率方案:在報表中僅包含開發人員方案。

設定預付餘額報表

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

欄位 說明
帳單月份

報表的帳單月份。

報表層級

報表層級。有效值包括:

  • 詳細:您可以分別顯示每個補充餘額,方便您與付款處理方支付的款項進行對帳。
  • 摘要:概略說明每位開發人員的總餘額。
公司

選取要納入報表的公司。如未選取,報表就會納入所有公司。

設定收益報表

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

欄位 說明
日期範圍

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

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

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

  • 當地幣別:報表中的每一行都會根據適用的費率方案顯示。 也就是說,如果開發人員計劃使用不同的貨幣,同一份報表中可能會包含多種貨幣。
  • 歐元:報表中會換算並以歐元顯示當地幣別交易。
  • 英鎊:報表中的當地幣別交易會以磅為單位進行換算。
  • 美元:報表中會換算並以美元顯示當地幣別交易。
報表層級

報表層級。有效值包括:

  • 詳細:分行顯示每筆交易。沒有任何摘要。
  • 摘要:根據您選取的參數,提供每個 API 產品和開發人員的總收益摘要。
產品組合

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

選取要納入報表的 API 產品套裝組合。如未選取任何 API,報表會包含所有 API 產品組合。

報表會依您選取的 API 產品組合分行列出。

針對摘要報表,您可以視需要在「摘要顯示」選項中勾選「不要顯示」。在這種情況下,報表會匯總所有 (或已選取) API 產品組合的資訊,而且不會分別列出各個 API 產品組合的資訊。

產品

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

報表會為您選取的每個 API 產品單獨列出一行。

針對摘要報表,您可以視需要在「摘要顯示」選項中勾選「不要顯示」。在此情況下,報表會匯總所有 (或已選取) 開發人員的資訊,而且不會分別列出每個所選開發人員的資訊。

公司

選取要納入報表的公司。如未選取,報表就會納入所有公司。

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

應用程式

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

報表會列出每個所選應用程式的獨立一行。

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

摘要顯示選項

報表所分組和顯示欄的順序。請選取數字,指出該區段在分組中的相對順序 (1 為第一個分組)。例如,下列內容會先依套件、產品、開發人員和應用程式分組,再對報表分組。

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

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

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

使用此功能需要仔細思考和規劃,因此請查看以下注意事項。

如果您是雲端客戶,請與 Apigee Edge 支援團隊聯絡以設定屬性。如果您是 Apigee Edge for Private Cloud 客戶,請使用 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 產品的資訊,且不會分別列出各個 API 產品的資訊。

公司

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

  • 全部:納入報表中的所有公司。
  • 已選取:顯示可納入報表的公司清單。如未選取任何公司,報表就會列出所有公司。

報表會為每間所選公司分別列出獨立的資料。

至於摘要報表,您可以視需要勾選「摘要顯示選項」區段中的 [不要顯示 (公司)] 選項。在這種情況下,報表會匯總所有 (或已選取) 公司的資訊,且不會分別列出每間所選公司的資訊。

應用程式

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

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

報表會列出每個所選應用程式的獨立一行。

至於摘要報表,您可以視需要勾選「摘要顯示選項」區段中的 [不要顯示 (應用程式)] 選項。在此情況下,報表會匯總所有 (或所選) 應用程式的資訊,且不會分別列出各個所選應用程式的資訊。

幣別

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

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

報表所分組和顯示欄的順序。請選取數字,指出該區段在分組中的相對順序 (1 為第一個分組)。例如,下列內容會先依套件、產品、開發人員和應用程式分組,再對報表分組。

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

正在產生報表和下載報表

建立報表後,您可以下載 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、開發人員、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,每頁傳回的 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} 代表開發人員的身分。提出要求時,您可以指定上述查詢參數,以篩選及排序資料。

例如,下列方法會傳回特定開發人員的報表設定,並依照報表名稱排序回應:

$ 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

報表內特定貨幣的編號和機構組織。如未指定這項屬性,報表會包含所有支援的貨幣。

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

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

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

不適用