使用非同步自訂報表 API

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

Edge Analytics 提供豐富的互動式資訊主頁、自訂報表產生器和相關功能。然而,這些功能的目的在於互動:您提交 API 或 UI 要求,但會在分析伺服器提供回應之前封鎖要求。

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

非同步查詢處理功能可讓您查詢非常龐大的資料集,並於日後擷取結果。如果互動式查詢逾時,您可以考慮使用離線查詢。非同步查詢處理作業在某些情況下,可能是不錯的替代方案:

  • 分析及建立橫跨大量時間間隔的報表。
  • 使用各種分組維度和其他限制來分析資料,增加查詢的複雜度。
  • 當您發現某些使用者或機構的資料量大幅增加時,就可以管理查詢。

本文件說明如何使用 API 啟動非同步查詢。您也可以使用 UI,如「執行自訂報表」所述。

比較報表 API 與使用者介面

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

透過使用者介面產生自訂報表的概念,大多適用於 API。也就是說,使用 API 建立自訂報表時,您可以指定 Edge 內建的metrics維度篩選器,以及使用 StatisticsCollector 政策建立的任何自訂指標。

UI 和 API 中產生的報表之間的主要差異是,使用 API 產生的報表會寫入 CSV 或 JSON (以換行符號分隔) 檔案,而不是寫入 UI 中顯示的視覺化報表。

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 主體中,指定定義報表的metrics維度篩選器

以下為 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 以外,enqueuedstate 也表示要求已成功。

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

回應範例:

如果查詢仍在進行中,您會收到類似下方的回應,其中 staterunning

{
    "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:(必要) 表格由metrics定義的指標名稱。
  • function:(非必要) 匯總函式,格式為 avgminmaxsum

    並非所有指標都支援所有匯總函式。metrics說明文件包含指定指標名稱的資料表,以及指標支援的函式 (avgminmaxsum)。

  • alias:(選用) 輸出內容中包含指標資料的具體名稱。如果省略,則預設值為指標名稱和匯總函式的名稱。
  • operator:(選用) 計算完值後要對指標執行的作業。適用於 value 屬性。支援的作業包括:+ - / % *
  • value:(選用) 依指定 operator 套用至計算指標的值。

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

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

詳情請參閱「Analytics (分析) 指標、維度和篩選器參考資料」一文。

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

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

  • last60minutes
  • last24hours
  • last7days

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

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}
limit 結果中可傳回的資料列數量上限。
filter 可用於篩選資料的布林運算式。篩選運算式可用「AND/OR」字詞加以組合,而且應該完整加上括號以避免混淆。如要進一步瞭解可用來篩選依據的欄位,請參閱 Analytics (分析) 指標、維度和篩選器參考資料。如要進一步瞭解用於建構篩選運算式的權杖,請參閱「篩選運算式語法」一文。
groupByTimeUnit 用來對結果集分組的時間單位。有效值包括:secondminutehourdayweekmonth

如果查詢包含 groupByTimeUnit,則結果是依據指定時間單位進行匯總,而結果時間戳記不含毫秒精確度。如果查詢省略 groupByTimeUnit,則結果時間戳記會包含毫秒精確度。

outputFormat 輸出格式。有效值包括:csvjson。預設為 json,對應至以換行符號分隔的 JSON。

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

csvDelimiter 如果 outputFormat 設為 csv,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。

右側範例的比對結果如下:

- 任何包含「buy」字詞的值

- 任何結尾為「item」的值

- 任何以「Prod」開頭的值

- 任何開頭為 4 的值,Note 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 可使用「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

來自 metricExpression.json 的要求主體

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

如何建立非同步營利報表查詢

你可以按照本節所述的步驟,擷取特定時間範圍內在某組條件內成功的所有營利交易。

與非同步分析查詢一樣,您可以透過三個步驟執行非同步營利報表查詢:(1) 提交查詢、(2) 取得查詢狀態,以及 (3) 擷取查詢結果。

步驟 1:提交查詢如下。

步驟 2 和 3 與非同步分析查詢完全相同。詳情請參閱「如何建立非同步分析查詢」一文。

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

如有需要,您可以傳送 environment 查詢參數來指定環境。如果未指定,查詢參數會預設為 prod。例如:

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

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

名稱 說明 預設 是否必要?
appCriteria 報表中要納入特定應用程式的 ID 和機構。如未指定這項屬性,報表會包含所有應用程式。 不適用
billingMonth 報表的帳單月份,例如 JULY。 不適用
billingYear 報表的帳單年分,例如 2015 年。 不適用
currencyOption 報表的貨幣。有效值包括:
  • LOCAL:報表的每一行都會顯示適用的房價方案。也就是說,如果開發人員計劃使用不同的貨幣,同一份報表中可能會包含多種貨幣。
  • EUR - 當地幣別交易會以歐元換算並顯示。
  • GPB - 當地幣別交易會以英鎊計算並顯示。
  • USD:當地幣別交易會以美元換算並顯示。

如果您選取歐元、英鎊或美元,報表就會根據交易日期的主要匯率,顯示使用這種貨幣的所有交易。

不適用
devCriteria

報表中要包含的開發人員 ID 或電子郵件地址,以及機構名稱。如未指定這項屬性,報表內會包含所有開發人員。

例如:

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

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

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

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

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

舉例來說,下列要求會針對指定 API 產品和開發人員 ID,產生 2017 年 6 月的非同步營利報表。報表 fromDatetoDate 的日期和時間採用世界標準時間/格林威治標準時間 (UTC/GMT),且可能包括時間。

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