使用非同步自訂報表 API

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

Edge Analytics 提供豐富的互動式資訊主頁、自訂報表產生器和相關功能。不過，這些功能是互動式功能：您提交 API 或 UI 要求後，系統會封鎖要求，直到 Analytics 伺服器提供回應為止。

不過，如果分析要求處理時間過長，可能會逾時。 如果查詢要求需要處理大量資料 (例如數百 GB)，則可能會因逾時而失敗。

非同步查詢處理功能可讓您查詢非常大的資料集，並在稍後擷取結果。如果互動式查詢逾時，不妨考慮使用離線查詢。在下列情況下，非同步查詢處理可能是不錯的替代方案：

  • 分析及建立涵蓋長時間間隔的報表。
  • 使用各種分組維度和其他限制分析資料，導致查詢變得複雜。
  • 如果發現部分使用者或機構的資料量大幅增加，請管理查詢。

本文說明如何使用 API 啟動非同步查詢。您也可以按照「執行自訂報表」一文的說明，使用使用者介面。

比較 Reports API 和使用者介面

「建立及管理自訂報表」一文說明如何使用 Edge UI 建立及執行自訂報表。您可以同步或非同步執行這些報表。

使用 API 生成自訂報表時，大部分概念都與使用 UI 相同。 也就是說，使用 API 建立自訂報表時，您會指定 Edge 內建的指標、維度和篩選條件，以及使用 StatisticsCollector 政策建立的任何自訂指標。

在使用者介面和 API 中產生的報表主要差異在於，透過 API 產生的報表會寫入 CSV 或 JSON (以換行符號分隔) 檔案，而不是顯示在使用者介面中的視覺化報表。

Apigee Hybrid 的限制

Apigee Hybrid 會強制執行結果資料集 30 MB 的大小限制。

如何發出非同步分析查詢

您需要三個步驟，才能發出非同步分析查詢：

  1. 提交查詢。

  2. 取得查詢狀態。

  3. 擷取查詢結果。

步驟 1：提交查詢

您必須將 POST 要求傳送至 /queries API。這個 API 會告知 Edge 在背景處理要求。如果查詢提交成功，API 會傳回 201 狀態和 ID，供您在後續步驟中參照查詢。

例如：

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries -d @json-query-file
-u orgAdminEmail:password

要求主體是查詢的 JSON 說明。在 JSON 主體中，指定定義報表的指標、維度和篩選器。

以下是 json-query-file 檔案範例：

{ 
   "metrics":  [
     {
         "name": "message_count",
         "function": "sum",
         "alias": "sum_txn"
    }
        ],
    "dimensions": ["apiproxy"],
    "timeRange": "last24hours",
    "limit": 14400,
    "filter":"(message_count ge 0)"         
}

如要完整瞭解要求主體語法，請參閱下方的「關於要求主體」。

回應範例：

請注意，查詢 ID 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd 會包含在回應中。除了 HTTP 狀態 201 之外，state 的 enqueued 也表示要求成功。

HTTP/1.1 201 Created

{  
  "self":"/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
  "created":"2018-05-10T07:11:10Z",
  "state":"enqueued",
  "error":"false",
}

步驟 2：取得查詢狀態

發出 GET 呼叫，要求查詢的狀態。您提供 POST 呼叫傳回的查詢 ID。例如：

curl -X GET -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd
-u email:password

回覆範例：

如果查詢仍在進行中，您會收到類似以下的回應，其中 state 為 running：

{
    "self": "/organizations/myorg/environments/myenv/queries/1577884c-4f48-4735-9728-5da4b05876ab",
    "state": "running",
    "created": "2018-02-23T14:07:27Z",
    "updated": "2018-02-23T14:07:54Z"
}

查詢成功完成後，您會看到類似以下的回應，其中 state 會設為 completed：

{
      "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
      "state": "completed",
      "result": {
        "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result",
        "expires": "2017-05-22T14:56:31Z"
      },
      "resultRows": 1,
      "resultFileSize": "922KB",
      "executionTime": "11 sec",
      "created": "2018-05-10T07:11:10Z",
      "updated": "2018-05-10T07:13:22Z"
}

步驟 3：擷取查詢結果

查詢狀態為 completed 後，您可以使用 get results API 擷取結果，查詢 ID 再次為 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd。

curl -X GET -H "Content-Type:application/json" -O -J https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result
-u email:password

如要擷取下載的檔案，請設定使用的工具，將下載的檔案儲存到系統中。例如：

  • 如果您使用 cURL，可以如上所示使用 -O -J 選項。

  • 如果使用 Postman，請選取「儲存並下載」按鈕。在這種情況下，系統會下載名為 response 的 ZIP 檔案。

  • 如果你使用 Chrome 瀏覽器，系統會自動接受下載要求。

如果要求成功，且結果集不為零，系統會將結果下載至用戶端，並以壓縮的 JSON (以換行符號分隔) 檔案形式儲存。下載的檔案名稱為：

OfflineQueryResult-<query-id>.zip

例如：

OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip

ZIP 檔案包含 JSON 結果的 .gz 封存檔。如要存取 JSON 檔案，請解壓縮下載的檔案，然後使用 gzip 指令擷取 JSON 檔案：

unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gz

關於要求主體

本節說明您可在查詢的 JSON 要求主體中使用的各項參數。如要進一步瞭解可在查詢中使用的指標和維度，請參閱 Analytics 參考資料。

{  
   "metrics":[  
      {  
        "name":"metric_name",
        "function":"aggregation_function",
        "alias":"metric_dispaly_name_in_results",
        "operator":"post_processing_operator",
        "value":"post_processing_operand"
      },
   ...
   ],
   "dimensions":[  
      "dimension_name",
      ...
   ],
   "timeRange":"time_range",
   "limit":results_limit,
   "filter":"filter",
   "groupByTimeUnit": "grouping",
   "outputFormat": "format",
   "csvDelimiter": "delimiter"
}
屬性 說明 是否必要？
metrics

指標陣列。您可以為查詢指定一或多項指標，每項指標都包含： 只需要提供指標名稱：

  • name：(必要) 指標名稱，如指標表格所定義。

  • function：(選用) 匯總函式，例如 avg、min、max 或 sum。

    並非所有指標都支援所有匯總函式。指標說明文件包含一個表格，其中會指定指標名稱和指標支援的函式 (avg、min、max、sum)。

  • alias：(選用) 輸出內容中包含指標資料的屬性名稱。 如果省略，預設值為指標名稱與彙整函式名稱的組合。
  • operator：(選用) 在計算指標值後對指標執行的作業。適用於 value 屬性。 支援的操作包括：+ - / % *。
  • value：(選用) 根據指定 operator 套用至計算指標的值。

operator 和 value 屬性會定義對指標執行的後續處理作業。舉例來說，如果您指定指標 response_processing_latency，指標會傳回平均回應處理延遲時間，單位為毫秒。如要將單位換算為秒，請將 operator 設為 "/"，並將 value 設為 ”1000.0“：

"metrics":[  
  {  
    "name":"response_processing_latency",
    "function":"avg",
    "alias":"average_response_time_in_seconds",
    "operator":"/",
    "value":"1000"
  }
]

詳情請參閱「數據分析指標、維度和篩選器參考資料」。

 否
dimensions 要將指標分組的維度陣列。詳情請參閱支援的維度清單。 您可以指定多個維度。 否
timeRange 查詢的時間範圍。

您可以使用下列預先定義的字串指定時間範圍：

  • last60minutes
  • last24hours
  • last7days

或者，您也可以將 timeRange 指定為結構，以 ISO 格式描述開始和結束時間戳記：yyyy-mm-ddThh:mm:ssZ。例如：

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}
 		是
limit 結果中可傳回的列數上限。 否
filter 可用於篩選資料的布林運算式。篩選器運算式可以使用 AND/OR 字詞組合，並應完全以半形括號括住，以免產生模稜兩可的情況。如要進一步瞭解可供篩選的欄位，請參閱「數據分析指標、維度和篩選器參考資料」。如要進一步瞭解用於建構篩選運算式的權杖，請參閱「篩選運算式語法」。 否
groupByTimeUnit 用於將結果集分組的時間單位。有效值包括：second、minute、hour、day、week 或 month。

如果查詢包含 groupByTimeUnit，則結果會是根據指定時間單位的匯總，且產生的時間戳記不會包含毫秒精確度。 如果查詢省略 groupByTimeUnit，則產生的時間戳記會精確至毫秒。

 否
outputFormat 輸出格式。有效值包括：csv 或 json。預設值為 json ，對應於以換行符號分隔的 JSON。

注意：使用 csvDelimiter 屬性設定 CSV 輸出的分隔符號。

 否
csvDelimiter CSV 檔案中使用的分隔符號 (如果 outputFormat 設為 csv)。預設為 , (半形逗號) 字元。支援的分隔符號包括半形逗號 (,)、直立線 (|) 和定位點符號 (\t)。 否

篩選運算式語法

本參考章節說明可用於在要求本文中建構篩選運算式的權杖。舉例來說，下列運算式使用「ge」權杖 (大於或等於)：

"filter":"(message_count ge 0)"
權杖 說明 範例
in 加入清單 
(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

注意： 字串必須加上引號。
notin 從清單中排除 
(response_status_code notin 400,401,500,501)
eq 等於 (==) 
(response_status_code eq 504)

(apiproxy eq 'non-prod')
ne 不等於 (!=) 
(response_status_code ne 500)

(apiproxy ne 'non-prod')
gt 大於 (>) 
(response_status_code gt 500)
lt 小於 (<) 
(response_status_code lt 500)
ge 大於或等於 (>=) 
(target_response_code ge 400)
le 小於或等於 (<=) 
(target_response_code le 300)
like 如果字串模式與提供的模式相符，則傳回 true。

右側範例的相符情形如下：

- 含有「購買」一詞的任何值

- 結尾為「item」的任何值

- 任何以「Prod」開頭的值

- 開頭為 4 的任何值，請注意 response_status_code 為數值 

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')
not like 如果字串模式與提供的模式相符，則傳回 false。 
(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')
and 可使用「and」邏輯納入多個篩選運算式。篩選器會納入符合所有條件的資料。 
(target_response_code gt 399) and (response_status_code ge 400)
or 可讓您使用「或」邏輯評估不同的可能篩選運算式。篩選器會納入符合至少一項條件的資料。 
(response_size ge 1000) or (response_status_code eq 500)

限制和預設值

以下列出非同步查詢處理功能的限制和預設值。

限制 預設 說明
查詢通話次數上限 請參閱說明 您每小時最多可以對 /queries 管理 API 發出七次呼叫，啟動非同步報表。如果超出呼叫配額，API 會傳回 HTTP 429 回應。
有效查詢限制 10 每個機構/環境最多可有 10 個有效查詢。
查詢執行時間門檻 6 小時 如果查詢時間超過 6 小時，系統會終止查詢。
查詢時間範圍 請參閱說明 查詢的時間範圍上限為 365 天。
維度和指標限制 25 您可以在查詢酬載中指定的維度和指標數量上限。

關於查詢結果

以下是 JSON 格式的結果範例。輸出內容包含以換行符號分隔的 JSON 列：

{"message_count":"10209","apiproxy":"guest-auth-v3","hour":"2018-08-07 19:26:00 UTC"}
{"message_count":"2462","apiproxy":"carts-v2","hour":"2018-08-06 13:16:00 UTC"}    
…

在存放區中的資料過期前，您都可以從網址擷取結果。請參閱「限制和預設值」。

範例

範例 1：訊息數量總和

查詢過去 60 分鐘的訊息計數總和。

查詢

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

last60minutes.json 的要求主體

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":"last60minutes"
}

範例 2：自訂時間範圍

使用自訂時間範圍查詢。

查詢

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1 /organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

last60minutes.json 的要求內文

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

範例 3：每分鐘交易數

查詢每分鐘交易數 (tpm) 的指標。

查詢

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @tpm.json
-u orgAdminEmail:password

tpm.json 的要求主體

{  
   "metrics":[  
      {  
         "name":"tpm"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-07-01T11:00:00Z",
      "end":"2018-07-30T11:00:00Z"
   }
}

範例結果

結果檔案的摘錄內容： 

{"tpm":149995.0,"apiproxy":"proxy_1","minute":"2018-07-06 12:16:00 UTC"}
{"tpm":149998.0,"apiproxy":"proxy_1","minute":"2018-07-09 15:12:00 UTC"}
{"tpm":3.0,"apiproxy":"proxy_2","minute":"2018-07-11 16:18:00 UTC"}
{"tpm":148916.0,"apiproxy":"proxy_1","minute":"2018-07-15 17:14:00 UTC"}
{"tpm":150002.0,"apiproxy":"proxy_1","minute":"2018-07-18 18:11:00 UTC"}
...

範例 4：使用篩選運算式

使用布林運算子的篩選運算式查詢。

查詢

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @filterCombo.json
-u orgAdminEmail:password

filterCombo.json 中的要求主體

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "filter":"(apiproxy ne \u0027proxy_1\u0027) and (apiproxy ne \u0027proxy_2\u0027)",
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

範例 5：在指標參數中傳遞運算式

使用以指標參數形式傳入的運算式進行查詢。您只能使用簡單的單一運算子運算式。

查詢

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" 
-d @metricsExpression.json
-u orgAdminEmail:password

metricsExpression.json 的要求主體

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum",
         "operator":"/",
         "value":"7"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":10,
   "timeRange":"last60minutes"
}

如何發出非同步營利報表查詢

按照本節所述步驟操作，即可擷取特定時間範圍內，符合特定條件的所有成功營利交易。

與非同步分析查詢一樣，非同步營利報表查詢也分為三個步驟：(1) 提交查詢、(2) 取得查詢狀態，以及 (3) 擷取查詢結果。

步驟 1 (提交查詢) 說明如下。

步驟 2 和 3 與非同步分析查詢完全相同。詳情請參閱「如何進行非同步 Analytics 查詢」。

如要提交非同步營利報表的查詢，請對 /mint/organizations/org_id/async-reports 發出 POST 要求。

您可以選擇傳遞 environment 查詢參數來指定環境。如未指定，查詢參數預設為 prod。例如：

/mint/organizations/org_id/async-reports?environment=prod

在要求主體中，指定下列搜尋條件。

名稱 說明 預設 必填與否
appCriteria 要納入報表的特定應用程式 ID 和機構。如未指定這項屬性，報表會納入所有應用程式。 N/A 否
billingMonth 報表的帳單月份，例如「JULY」。 N/A 是
billingYear 報表的帳單年度，例如 2015 年。 N/A 是
currencyOption 報表的幣別。有效值包括：
  • LOCAL - 報表的每一行都會顯示適用的費率方案。也就是說，如果開發人員的方案使用不同幣別，一份報表可能包含多種幣別。
  • EUR - 系統會將當地幣別交易換算為歐元並顯示。
  • GPB - 系統會將當地幣別交易換算為英鎊並顯示。
  • USD - 系統會將當地幣別交易換算成美元並顯示。

如果選取歐元、英鎊或美元，報表會根據交易當天的有效匯率，顯示所有以該單一貨幣進行的交易。

 N/A 否
devCriteria

開發人員 ID 或電子郵件地址，以及特定開發人員的機構名稱， 將納入報表。如未指定這項屬性，報表會納入所有開發人員。

例如：

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]
 		N/A 否
fromDate 報表的開始日期 (世界標準時間)。 N/A 是
monetizationPakageIds 要納入報表的一或多個 API 套件 ID。如未指定這項屬性，報表會納入所有 API 套件。 N/A 否
productIds 要納入報表的一或多個 API 產品 ID。如未指定這項屬性，報表會納入所有 API 產品。 N/A 否
ratePlanLevels

要納入報表的費率方案類型。有效值包括：

  • DEVELOPER：開發人員費率方案。
  • STANDARD - 標準費率方案。

如未指定這項屬性，報表會同時納入開發人員專屬和標準費率方案。

 N/A 否
toDate 報表的結束日期 (世界標準時間)。 不適用 是

舉例來說，下列要求會針對指定的 API 產品和開發人員 ID，產生 2017 年 6 月的非同步營利報告。報表 fromDate 和 toDate 的日期和時間以世界標準時間/格林威治標準時間為準，且可能包含時間。

curl -H "Content-Type:application/json" -X POST -d \
'{
      "fromDate":"2017-06-01 00:00:00",
      "toDate":"2017-06-30 00:00:00",    
     "productIds": [
        "a_product"
    ],
    "devCriteria": [{
        "id": "AbstTzpnZZMEDwjc",
        "orgId": "myorg"
    }]

 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/async-reports?environment=prod" \
-u orgAdminEmail:password